Loading and Saving Data
Simple importing and exporting of imaging data is a significant source of boilerplate code in most processing pipelines.
The io_tools
module provides a few functions for loading, converting, and saving imaging
data with very simple syntax and good performance. Currently, *.tif, *.gif, *.mp4, and *.bin (binary) file
types are supported. Every function either returns or expects the images in the form of a
numpy arrays
with shape frames, y-pixels, x-pixels. They also all use a similar syntax:
load_{file_type}(path) for loading and save_{file_type}(path, images) for saving.
Note
Color videos and gifs additionally accept numpy arrays
with
shape frames, y-pixels, x-pixels, color.
Loading .tif’s
CalScipy offers a single, simple function for loading images with the *.tif file format and other closely associated
formats like *.ome.tiff: load_images
.
Loading a 2D-image
images = load_images("single_image.tif")
Loading a 3D-stack
images = load_images("imaging_stack.tif")
Loading entire folders of imaging stacks
images = load_images("imaging_folder")
Easy, huh?
Saving .tif’s
CalScipy also offers a single, simple function for saving images with the *.tif file format. If the image size is larger the size_cap limit, the stack will be automatically split into chunks of size size_cap. By default, the size_cap is set to limit .tif stacks to less than 4GB each for compatibility with the majority of *.tif readers.
Saving images to file
save_images("single_image.tif", images)
Saving images to a folder
save_images("desired_folder", images)
Saving images to a folder with specified name
save_images("desired_folder", images, name="example_images")
Loading .bin’s
Binary data in CalSciPy can be loaded using the load_binary
function with a
similar syntax. However, additional arguments are available to load the images without reading the entire file into
memory (i.e., memory-mapping).
Loading binary data directly from file
images = load_binary("binary.bin")
Loading binary data directly from a folder
images = load_binary("desired_folder")
Loading memory mapped binary data
images = load_binary("desired_folder", mapped=True, mode="r")
Loading binary data with missing metadata
missing_metadata = {"frames": 100, "y": 100, "dtype": int}
images = load_binary("desired_folder", missing_metadata=missing_metadata)
Saving .bin’s
Binary data can be saved to file using the save_binary <CalSciPy.io_tools.save_binary()
function.
Saving binary to file
save_binary("binary_file.bin", images)
Saving binary to folder
save_binary("desired_folder", images)
Saving binary to folder with specified name
save_binary("desired_folder", images, name="example_binary")
Tip
This language-agnostic format is ideal for optimal read/write speeds, larger-than-memory data, and is highly-robust to corruption. However, it does have downsides. First, the images and their metadata are split into two separate files: “.bin” and “.json” respectively. If you happen to lose the metadata file, fear not! As long as you have the datatype and 2 of the 3 dimensions you can still load the data. A second disadvantage is a lack of compression. Using binary is excellent in cases where storage space is “cheaper” than I/O time: for example, when data is still being regularly accessed and not simply sitting in “cold storage”.
Loading .mp4’s
Loading *.mp4's uses the load_video
function, returning the video as
a numpy array
with shape frames, y-pixels, x-pixels, colors.
Loading video from file
images = load_video("video_file.mp4")
Loading video from folder
images = load_video("desired_folder")
Saving .mp4’s
Saving *.mp4's uses the save_video
function. The frame rate of the video can be
set with the frame_rate argument.
Saving video to file
save_video("video_file.mp4", images)
Saving video to folder
save_video("desired_folder", images)
Saving video to folder with specified name
save_video("desired_folder", images, name="example_binary")
Saving video to folder with specified framerate
save_video("video_file.mp4", images, frame_rate=90.0)
Loading .gif’s
Loading *.gif's uses the load_gif
function.
Loading a *.gif
gif = load_gif("gif_file.gif")
Saving .gif’s
Saving your images as a *.gif is as easy as using the save_gif
function.
Saving a *.gif
save_gif("gif_file.gif", images, frame_rate=5.0)
Tip
Inserting videos into a presentation as a *.gif is a clever way to avoid technical difficulties (shudder).