Reading and writing¶

The format of a file is worked out from the file when it is read, and from its extension when it is written.

Whole files¶

vitrio.query_descriptor(key, readers=None)¶

Get the shape and data type of what an image file holds.

The extents are those of the whole file, slowest axis first, so a stack reports the axis it stacks along before the shape of one of its images. get_core_extents leaves that axis out, which is the shape a batch destination carries beside its leading extent:

descriptor = query_descriptor(path)
destination = np.empty(
        (len(locations), *get_core_extents(descriptor)),
        dtype=np.float32
)

Parameters:

key – The file to ask about, as its key in readers.
readers – Where the file becomes a reader. Defaults to a provider that opens the file at the path key is.

Returns:

The descriptor of the file.

Return type:

ImageDescriptor

vitrio.read(location, readers=None, data_type=None, out=None)¶

Read an image file, or one image or volume of a stack.

Parameters:

location – The file to read, as its key in readers, or an ImageLocation naming one image or volume of it. A string is a key and only a key: read “3@stack.mrc” by handing it to ImageLocation.from_string first.
readers – Where the file becomes a reader. Defaults to a provider that opens the file at the path the key is.
data_type – The type to read the values as. Defaults to the one the file holds. Cannot be given with out, whose own type is the one the values are read as.
out – The array to read into. Its shape has to be that of what location names. Defaults to a new Array.

Returns:

out when it is given. Otherwise an Array over memory of its own, which numpy and whatever takes DLPack use without a copy.

Raises:

ValueError – If data_type and out are both given.

vitrio.write_single(array, path, formats=None, data_type=None)¶

Write an array to an image file as one image or volume.

Parameters:

array – The values to write.
path – The file to write them to.
formats – The formats to choose from. Defaults to the bundled ones.
data_type – The type to store the values as. Defaults to the one the array already carries.

vitrio.write_stack(array, path, formats=None, data_type=None)¶

Write an array to an image file as a stack of images or volumes.

The leading extent of the array is the axis the file stacks along and the rest are the shape of one image or volume.

Parameters:

array – The values to write.
path – The file to write them to.
formats – The formats to choose from. Defaults to the bundled ones.
data_type – The type to store the values as. Defaults to the one the array already carries.

vitrio.write(array, path, descriptor, formats=None)¶

Write an array to an image file as a descriptor states.

The core rank of the descriptor is what makes the file a stack and not a single image or volume, and its data type is the one the file stores.

Parameters:

array – The values to write. Its shape has to be the extents of descriptor.
path – The file to write them to.
descriptor – What the file holds.
formats – The formats to choose from. Defaults to the bundled ones.

Batches and patches¶

A batch is read or written on the threads of a loader or a saver, and its images may come from any number of files.

vitrio.read_batch_async(loader: vitrio._binding.ImageLoader, destination: ndarray[device='cpu'], locations: collections.abc.Sequence[vitrio._binding.ImageLocation]) → vitrio._binding.Completion¶

Read one image or volume per location into a batch.

Returns before the reads are done. Slot i of destination receives the image locations[i] names, or the whole file when it names no index in a stack. A batch may not mix the two. The images may come from any number of files, and the reads run on the loader’s executor.

Parameters:

loader – The ImageLoader the reads are dispatched to.
destination – Where the images land, as any host array, written where it is. Its leading extent is the batch size and the rest are the shape of one image. Its data type is the one the values are read as.
locations – A list of ImageLocation, one for each slot, in order.

Returns:

Ready once every image is in or has failed. It keeps destination alive, and destroying it waits for the reads. Its get raises the first failure, such as an index its stack does not hold.

Return type:

Completion

Raises:

ValueError – If the leading extent of destination is not the number of locations, or if the locations mix those that name an index with those that name none.

vitrio.read_patches_async(loader, destination, location, centres)¶

Crop a batch of equally sized patches out of one image.

Returns before the reads are done. Each slot of destination receives the patch around one centre, which lands at index extent // 2 within it. A patch reaching past the edge of the image is read as far as the image goes, and the rest of its slot keeps what destination held beforehand.

Parameters:

loader – Where the reads are dispatched.
destination – Where the patches land. Its leading extent is the batch size and the rest are the shape of one patch.
location – The image every patch is cropped from.
centres – The centre of each patch: an IndexTable, an array of integers with one row per centre, or any sequence of sequences. Each centre has the rank of one patch.

Returns:

Ready once every patch has been read or has failed. It keeps destination alive, and destroying it waits for the reads.

Return type:

Completion

vitrio.write_batch_async(saver: vitrio._binding.ImageSaver, source: ndarray[device='cpu', writable=False], locations: collections.abc.Sequence[vitrio._binding.ImageLocation]) → vitrio._binding.Completion¶

Write one image or volume per location out of a batch.

Returns before the writes are done. Slot i of source goes where locations[i] names. The files have to be declared with their final shape beforehand, on the provider the saver writes through, so a stack can be written a batch at a time, and one batch may span several stacks.

Parameters:

saver – The ImageSaver the writes are dispatched to.
source – The values, as any host array, read from where it is. Its leading extent is the batch size and the rest are the shape of one image.
locations – A list of ImageLocation, one for each slot, in order.

Returns:

Ready once every image is written or has failed. It keeps source alive, and destroying it waits for the writes. Its get raises the first failure.

Return type:

Completion

Raises:

ValueError – If the leading extent of source is not the number of locations, or if the locations mix those that name an index with those that name none.

class vitrio.Completion¶

What an asynchronous read or write returns to wait on.

It is ready once all the work behind it has run, successfully or not. Call get to wait for it and to learn whether anything failed. The completion keeps the arrays the work reads or writes alive, and destroying one that is not ready waits for it.

get(self) → None¶

Block until the work is done, then raise the first failure.

The GIL is released meanwhile.

Raises:: Exception – Whatever the first piece of work to fail raised.

property is_ready¶: Whether the work is done, successfully or not.

wait(self) → None¶

Block until the work is done.

It does not raise whatever failed. The GIL is released meanwhile.