ImageStackSQL

class ImageStackSQL(database='', stack_name='', dtype=<class 'numpy.float32'>, max_size_mb=None, cache_limit=80)[source]

This class works the same as ImageStack.

ImageStackSQL objects will track the amount of memory the images occupy. When the memory limit if surpassed, all data will be stored in an sqlite database and the RAM will be cleared. Only a lazy loaded object is left in the image stack. Only when directly accessing the images in the stack they will be loaded into RAM again. sqlalchemy is used to connect to the database in which all data is stored.

This makes this container suitable for long term storage and transfer of a lot of images. The images can be loaded into an ImageStackSQL object in a new python session.

Parameters

database: str, optional: Path of the database. If it does not exist, it will be created. If none is entered, the name is id(object)
stack_name: str, optional: The name of the table the images will be saved. If none is entered it will be id(object)
dtype: optional, default=np.float32: The dtype all images will be converted to. E.g. np.float32, bool, etc.
max_size_mb: float, optional: The maximal size in mb the image stack is allowed to be. If a new image is added after surpassing this size all images will be saved in the database and the occupied RAM is cleared. All images are still accessible but will be loaded only when directly accessed.
cache_limit: float, optional, default=90: The limit of the RAM usage in percent of the available system RAM. When the RAM usage of the system surpasses this limit, all images will be saved in the database and RAM is freed again even it max_size_mb is not reached. This makes sure that the system never runs out of RAM. Values over 100 will effectively deactivate this behaviour. If the total size of the image stack is too small to free enough RAM to reach the cache limit newly added images will be saved immediately in the database. This also lead to constant reads from the database as no images will be kept im RAM. Therefore it is recommended to set this well over the current RAM usage of the system when instantiating an object.

Attributes

nbytes: Sum of bytes for all currently fully loaded images.

Methods

`add_image`(img)	Add an image to the stack.
`change_dtype`(dtype)	Change the dtype of all images in the stack.
`copy`([stack_name])	Copy the current image stack.
`execute_function`(func, args, *kwargs)	Perform an operation on all the images in the stack.
`execute_rolling_function`(func[, keep_first])	Perform an rolling operation on all the images in the stack.
`from_paths`(paths[, database, stack_name, ...])	Make an ImageStackSQL object directly form paths of images.
`load_from_database`([database, stack_name])	Load an image stack from a database.
`relaod`()	Reload the images form the table.
`remove_image`([i])	Remove an image from the stack.
`save_state`()	Saves the current state of the image stack to the database.

add_image(img)[source]

Add an image to the stack. The image must be a numpy array

The input array will be converted to the dtype of the ImageStack

Parameters

img: np.ndarray

change_dtype(dtype)[source]

Change the dtype of all images in the stack. All images will be converted to the new dtype.

Parameters

dtype

copy(stack_name='')[source]

Copy the current image stack.

A new table in the database is created where all images are stored.

Parameters

stack_name: str: The name of the stack. This is also the name of the new table in the database

Returns

out: ImageStack

execute_function(func, *args, **kwargs)[source]

Perform an operation on all the images in the stack.

The operation can be any function which takes one images and other arguments as input and returns only one image.

This operation changes the images in the stack. If the current state should be kept copy the stack first.

Parameters

func: function: A function which takes ONE image as first input and returns ONE image.
args:: args are forwarded to the func.
kwargs:: kwargs are forwarded to the func.

Examples

>>> def fun(img, to_add):
>>>     return img + to_add

>>> stack.execute_function(fun, to_add=4)
This will apply the function *fun* to all images in the stack.

execute_rolling_function(func, keep_first=False, *args, **kwargs)[source]

Perform an rolling operation on all the images in the stack.

The operation can be any function which takes two images and other arguments as input and returns only one image.

\(I_{new} = func(I_{n-1}, I_n)\)

This operation changes the images in the stack. If the current state should be kept copy the stack first.

Since the 0-th image in the stack will remain unchanged because the rolling operation starts at the 1-st image, the 0-th image is removed if keep_first is set to False (default).

Parameters

func: function: A function which takes TWO images and other arguments as input and returns ONE image. The function must have the following input structure: fun(img1, img2, args, kwargs). img1 will be the n-1st image in the calls.
keep_first: bool: If True, keeps the first image in the stack. Delete it otherwise.
args:: args are forwarded to the func.
kwargs:: kwargs are forwarded to the func.

Examples

>>> def fun(img1, img2):
>>>     mask = img1 > img1.max()/2
>>>     return img2[mask]

>>> stack.execute_rolling_function(fun, keep_first=False)
This will apply the function *fun* to all images in the stack.

img1 is always the n-1st image in the rolling operation.

classmethod from_paths(paths, database='', stack_name='', dtype=None, max_size_mb=None, cache_limit=80, **kwargs)[source]

Make an ImageStackSQL object directly form paths of images. The images will be loaded, converted to the dtype of the ImageStack and added.

Parameters

paths: list: paths of the images to be added
database: str, optional: Path of the database. If it does not exist, it will be created. If none is entered, the name is id(object)
stack_name: str, optional: The name of the table the images will be saved. If none is entered it will be id(object)
dtype: optional: The dtype all images will be converted to. E.g. np.float32, bool, etc. If this is not set, the dtype of the first image loaded will determine the dtype of the stack.
max_size_mb: float, optional: ImageStackSQL for more details.
cache_limit: float, optional, default=90: :class`ImageStackSQL` for more details.
kwargs:: kwargs are forwarded to skimage.io.imread For grayscale images simply add as_gray = True. For the kwargs for colored images use parameters for reading. Keep in mind that some images might have alpha channels and some not even if they have the same format.

Returns

out: ImageStackSQL: A new ImageStackSQL object with connection to the database.

classmethod load_from_database(database='', stack_name='')[source]

Load an image stack from a database.

A table of a database which was made with an ImageStackSQL object can be loaded and an ImageStackSQL object with all the images is made. The dtype of the images in the new object is the same as the images in the table. All images, which will be added to the object will be converted to match the dtype.

Parameters

database: str: Path of the database.
stack_name: str: Name of the table

Returns

out: ImageStackSQL: The image stack object with connection to the database.

property nbytes

Sum of bytes for all currently fully loaded images.

This tracks the used RAM from the images. The overhead of the used RAM from sqlalchemy is not included and will not be tracked.

relaod()[source]: Reload the images form the table. All not saved changes will be lost.

remove_image(i=-1)[source]

Remove an image from the stack.

Parameters

i: int: Index of the image to be removed

save_state()[source]

Saves the current state of the image stack to the database.

This commits all changes and adds all new images to the table. All currently loaded images are expired. This means, that all RAM used by the images is freed.

Call this method before closing the python session if the changes made to the image stack should be saved permanently.