Modelhub Library

Overview of the classes of the Modelhub library.

Model

class modelhublib.model.ModelBase[source]

Abstract base class for contributer models. Currently this is merely an interface definition that all contributer implemented models have to follow.

infer(input)[source]

Abstract method. Overwrite this method to implement the inference of a model.

Parameters:input (str) – Input file name.
Returns:Converted inference results into format as defined in the model configuration. Usually should return the result of <YourImageProcessor>.computeOutput

Pre- and Postprocessing

class modelhublib.processor.ImageProcessorBase(config)[source]

Abstract base class for image pre- and postprocessing, thus handeling all data processing before and after the inference.

Several methods of this class have to be implemented in a contributed model. Follow the “Contribute Your Model to Modelhub” guide for detailed instructions.

An image processor handles:

  1. Loading of the input image(s).
  2. Converting the loaded images to a numpy array
  3. Preprocessing the image data (either on the image object or on the numpy array) After this step the data should be prepared to be directly feed to the inference step.
  4. Processing the inference result and convert it to the expected output format.

This class already provides loading and conversion of images using PIL and SimpleITK. If you need to support image formats which are not covered by those two, you should implement an additional ImageLoader and ImageConverter. If you do so, you will also need to overwrite the constructor (__init__) to instantiate your loader and converter and include them in the chain of responsibility. Best practice would be to call the original constructor from your derived class and then change what you need to change.

Parameters:config (dict) – Model configuration (loaded from model’s config.json)
loadAndPreprocess(input, id=None)[source]

Loads input, preprocesses it and returns a numpy array appropriate to feed into the inference model (4 dimensions: [batchsize, z/color, height, width]).

There should be no need to overwrite this method in a derived class! Rather overwrite the individual preprocessing steps used by this method!

Parameters:
  • input (str) – Name of the input file to be loaded
  • id (str or None) – ID of the input when handling multiple inputs
Returns:

numpy array appropriate to feed into the inference model (4 dimensions: [batchsize, z/color, height, width])

computeOutput(inferenceResults)[source]

Abstract method. Overwrite this method to define how to postprocess the inference results computed by the model into a proper output as defined in the model configuration file.

Parameters:inferenceResults – Results of the inference as computed by the model.
Returns:Converted inference results into format as defined in the model configuration.
_load(input, id=None)[source]

Performs the actual loading of the image.

There should be no need to overwrite this method in a derived class! Rather implement an additional ImageLoader to support further image formats. See also documentation of ImageProcessorBase above.

Parameters:
  • input (str) – Name of the input file to be loaded
  • id (str or None) – ID of the input when handling multiple inputs
Returns:

Image object which type will be the native image object type of the library/handler used for loading (default implementation uses PIL or SimpleITK). Hence it might not always be the same.

_preprocessBeforeConversionToNumpy(image)[source]

Perform preprocessing on the loaded image object (see _load()).

Overwrite this to implement image preprocessing using the loaded image object. If not overwritten, just returns the image object unchanged.

When overwriting this, make sure to handle the possible types appropriately and throw an IOException if you cannot preprocess a certain type.

Parameters:image (type = return of _load()) – Loaded image object
Returns:Image object which must be of the same type as input image object.
_convertToNumpy(image)[source]

Converts the image object into a corresponding numpy array with 4 dimensions: [batchsize, z/color, height, width].

There should be no need to overwrite this method in a derived class! Rather implement an additional ImageConverter to support further image format conversions. See also documentation of ImageProcessorBase above.

Parameters:image – (type = return of _preprocessBeforeConversionToNumpy()): Loaded and preproceesed image object.
Returns:Representation of the input image as numpy array with 4 dimensions [batchsize, z/color, height, width].
_preprocessAfterConversionToNumpy(npArr)[source]

Perform preprocessing on the numpy array (the result of _convertToNumpy()).

Overwrite this to implement preprocessing on the converted numpy array. If not overwritten, just returns the input array unchanged.

Parameters:npArr (numpy array) – input data after conversion by _convertToNumpy()
Returns:Preprocessed numpy array with 4 dimensions [batchsize, z/color, height, width].

Image Loading

class modelhublib.imageloaders.imageLoader.ImageLoader(config, successor=None)[source]

Abstract base class for image loaders, following chain of responsibility design pattern. For each image loader you should implement a corresponding image converter using ImageConverter as base class.

Parameters:sucessor (ImageLoader) – Next loader in chain to attempt loading the image if this one fails.
setSuccessor(successor)[source]

Setting the next loader in chain of responsibility.

Parameters:sucessor (ImageLoader) – Next loader in chain to attempt loading the image if this one fails.
load(input, id=None)[source]

Tries to load input and on fail forwards load request to next handler until success or final fail.

There should be no need to overwrite this. Overwrite only _load() to load the image type you want to support and let this function as it is to handle the chain of responsibility and errors.

Parameters:input (str) – Name of the input file to be loaded.
Returns:Image object as loaded by _load() or a successor load handler.
Raises:IOError if input could not be loaded by any load handler in the chain.
_load(input)[source]

Abstract method. Overwrite to implement loading of the input format you want to support.

When overwriting this, make sure to raise IOError if input cannot be loaded.

Parameters:input (str) – Name of the input file to be loaded.
Returns:Should return image object in the native format of the library using to load it.
_checkConfigCompliance(image, id=None)[source]

Checks if image complies with configuration.

There should be no need to overwrite this. Overwrite only _getImageDimensions() to supply the image dims to check against config.

Parameters:image – Image object as loaded by _load()
Raises:IOError if image dimensions do not comply with configuration.
_getImageDimensions(image)[source]

Abstract method. Should return the dimensions of the loaded image, should be a 3 tuple (z, y, x).

Overwrite this in an implementation of this interface. This function is used by _checkConfigCompliance().

Parameters:image – Image object as loaded by _load()
Returns:Should return image dimensions of the image object.
class modelhublib.imageloaders.pilImageLoader.PilImageLoader(config, successor=None)[source]

Bases: modelhublib.imageloaders.imageLoader.ImageLoader

Loads common 2d image formats (png, jpg, …) using Pillow (PIL).

_load(input)[source]

Loads input using PIL.

Parameters:input (str) – Name of the input file to be loaded
Returns:PIL.Image object
_getImageDimensions(image)[source]
Parameters:image (PIL.Image) – Image as loaded by _load()
Returns:Image dimensions from PIL image object
class modelhublib.imageloaders.sitkImageLoader.SitkImageLoader(config, successor=None)[source]

Bases: modelhublib.imageloaders.imageLoader.ImageLoader

Loads image formats supported by SimpleITK

_load(input)[source]

Loads input using SimpleITK.

Parameters:input (str) – Name of the input file to be loaded
Returns:SimpleITK.Image object
_getImageDimensions(image)[source]
Parameters:image (SimpleITK.Image) – Image as loaded by _load()
Returns:Image dimensions from SimpleITK image object

Image Conversion

class modelhublib.imageconverters.imageConverter.ImageConverter(successor=None)[source]

Abstract base class for image converters, following chain of responsibility design pattern. For each image loader derived from ImageLoader you should implement a corresponding image converter using this as base class.

Parameters:sucessor (ImageConverter) – Next converter in chain to attempt loading the image if this one fails.
setSuccessor(successor)[source]

Setting the next converter in chain of responsibility.

Parameters:sucessor (ImageConverter) – Next converter in chain to attempt loading the image if this one fails.
convert(image)[source]

Tries to convert image to numpy and on fail forwards convert request to next handler until sucess or final fail.

There should be no need to overwrite this. Overwrite only _convert() to convert the image type you want to support and let this function as it is to handle the chain of responsibility and errors.

Parameters:image – Image object to convert.
Returns:Numpy array as converted by _convert() or a successor converter.
Raises:IOError if image could not be converted by any converter in the chain.
_convert(image)[source]

Abstract method. Overwrite to implement image conversion to numpy array from the image object type you want to support.

When overwriting this, make sure to raise IOError if image cannot be converted.

Parameters:image – Image object to convert.
Returns:Should return image object converted to numpy array with 4 dimensions [batchsize, z/color, height, width]
class modelhublib.imageconverters.pilToNumpyConverter.PilToNumpyConverter(successor=None)[source]

Bases: modelhublib.imageconverters.imageConverter.ImageConverter

Converts PIL.Image objects to Numpy

_convert(image)[source]
Parameters:image (PIL.Image) – Image object to convert.
Returns:Input image object converted to numpy array with 4 dimensions [batchsize, z/color, height, width]
Raises:IOError if input is not of type PIL.Image or cannot be converted for other reasons.
class modelhublib.imageconverters.sitkToNumpyConverter.SitkToNumpyConverter(successor=None)[source]

Bases: modelhublib.imageconverters.imageConverter.ImageConverter

Converts SimpltITK.Image objects to Numpy

_convert(image)[source]
Parameters:image (SimpleITK.Image) – Image object to convert.
Returns:Input image object converted to numpy array with 4 dimensions [batchsize, z/color, height, width]
Raises:IOError if input is not of type SimpleITK.Image or cannot be converted for other reasons.