coremltools.models.neural_network.flexible_shape_utils

Utilities to annotate Neural Network Features with flexible shape information. Only available in coremltools 2.0b1 and onwards

Functions

add_enumerated_image_sizes(spec, …) Annotate an input or output image feature in a Neural Network spec to to accommodate a list of enumerated image sizes
add_enumerated_multiarray_shapes(spec, …) Annotate an input or output multiArray feature in a Neural Network spec to to accommodate a list of enumerated array shapes
add_multiarray_ndshape_enumeration(spec, …) Annotate an input or output MLMultiArray feature in a Neural Network spec to accommodate a range of shapes.
can_allow_multiple_input_shapes(spec) Examines a model specification and determines if it can compute results for more than one output shape.
get_allowed_shape_ranges(spec) For a given model specification, returns a dictionary with a shape range object for each input feature name.
set_multiarray_ndshape_range(spec, …) Annotate an input or output MLMultiArray feature in a Neural Network spec to accommodate a range of shapes.
update_image_size_range(spec, feature_name, …) Annotate an input or output Image feature in a Neural Network spec to to accommodate a range of image sizes
update_multiarray_shape_range(spec, …) Annotate an input or output MLMultiArray feature in a Neural Network spec to accommodate a range of shapes

Classes

NeuralNetworkImageSize([height, width]) An object representing a size for an image feature inside a neural network.
NeuralNetworkImageSizeRange([height_range, …]) An object representing a range of sizes for an image feature inside a neural network.
NeuralNetworkMultiArrayShape([channel, …]) An object representing a shape for a multiArray feature in a neural network.
NeuralNetworkMultiArrayShapeRange([input_ranges]) An object representing a range of shapes for a multiArray feature in a neural network.
Shape(shape_value)
ShapeRange(lowerBound, upperBound)
Size(size_value)
class coremltools.models.neural_network.flexible_shape_utils.NeuralNetworkImageSize(height=None, width=None)

An object representing a size for an image feature inside a neural network. Valid sizess for height and width are > 0.

__init__(self, height=None, width=None)
class coremltools.models.neural_network.flexible_shape_utils.NeuralNetworkImageSizeRange(height_range=None, width_range=None)

An object representing a range of sizes for an image feature inside a neural network. Valid ranges for height and width are > 0. A “-1” upper bound value for either width or height represents an unbounded size for that dimension.

__init__(self, height_range=None, width_range=None)
class coremltools.models.neural_network.flexible_shape_utils.NeuralNetworkMultiArrayShape(channel=None, height=None, width=None)

An object representing a shape for a multiArray feature in a neural network. Valid shapes must have have only the Channel [C] shape or the Channel, Height and Width [C, H, W] shapes populated

__init__(self, channel=None, height=None, width=None)
class coremltools.models.neural_network.flexible_shape_utils.NeuralNetworkMultiArrayShapeRange(input_ranges=None)

An object representing a range of shapes for a multiArray feature in a neural network. Valid shape ranges must have have only the Channel [C] range or the Channel, Height and Width [C, H, W] ranges populated. A “-1” value in an upper bound represents an unbounded range.

__init__(self, input_ranges=None)
isFlexible(self)

Returns true if any one of the channel, height, or width ranges of this shape allow more than one input value.

coremltools.models.neural_network.flexible_shape_utils.add_enumerated_image_sizes(spec, feature_name, sizes)

Annotate an input or output image feature in a Neural Network spec to to accommodate a list of enumerated image sizes

Parameters:
  • spec – MLModel The MLModel spec containing the feature
  • feature_name – str The name of the image feature for which to add size information. If the feature is not found in the input or output descriptions then an exception is thrown
  • sizes – [] | NeuralNetworkImageSize A single or a list of NeuralNetworkImageSize objects which encode valid size information for a image feature

Examples

>>> import coremltools
>>> from coremltools.models.neural_network import flexible_shape_utils
>>> spec = coremltools.utils.load_spec('mymodel.mlmodel')
>>> image_sizes = [flexible_shape_utils.NeuralNetworkImageSize(128, 128)]
>>> image_sizes.append(flexible_shape_utils.NeuralNetworkImageSize(256, 256))
>>> flexible_shape_utils.add_enumerated_image_sizes(spec, feature_name='my_multiarray_featurename', sizes=image_sizes)
Returns:None. The spec object is updated
coremltools.models.neural_network.flexible_shape_utils.add_enumerated_multiarray_shapes(spec, feature_name, shapes)

Annotate an input or output multiArray feature in a Neural Network spec to to accommodate a list of enumerated array shapes

Parameters:
  • spec – MLModel The MLModel spec containing the feature
  • feature_name – str The name of the image feature for which to add shape information. If the feature is not found in the input or output descriptions then an exception is thrown
  • shapes – [] | NeuralNetworkMultiArrayShape A single or a list of NeuralNetworkImageSize objects which encode valid size information for a image feature

Examples

>>> import coremltools
>>> from coremltools.models.neural_network import flexible_shape_utils
>>> spec = coremltools.utils.load_spec('mymodel.mlmodel')
>>> array_shapes = [flexible_shape_utils.NeuralNetworkMultiArrayShape(3)]
>>> second_shape = flexible_shape_utils.NeuralNetworkMultiArrayShape()
>>> second_shape.set_channel_shape(3)
>>> second_shape.set_height_shape(10)
>>> second_shape.set_width_shape(15)
>>> array_shapes.append(second_shape)
>>> flexible_shape_utils.add_enumerated_multiarray_shapes(spec, feature_name='my_multiarray_featurename', shapes=array_shapes)
Returns:None. The spec object is updated
coremltools.models.neural_network.flexible_shape_utils.add_multiarray_ndshape_enumeration(spec, feature_name, enumerated_shapes)

Annotate an input or output MLMultiArray feature in a Neural Network spec to accommodate a range of shapes. Add provided enumerated shapes to the list of shapes already present. This method is different from “add_enumerated_multiarray_shapes”, which is applicable for rank 5 mapping, SBCHW, arrays.

Parameters:
  • spec – MLModel The MLModel spec containing the feature
  • feature_name – str The name of the feature for which to add shape range information. If the feature is not found in the input or output descriptions then an exception is thrown
  • enumerated_shapes – List[Tuple(int)] list of shapes, where each shape is specified as a tuple of integers.

Examples

>>> import coremltools
>>> from coremltools.models.neural_network import flexible_shape_utils
>>> spec = coremltools.utils.load_spec('mymodel.mlmodel')
>>> # say, the default shape of "my_multiarray_featurename" is (2,3)
>>> flexible_shape_utils.add_multiarray_ndshape_enumeration(spec, feature_name='my_multiarray_featurename', enumerated_shapes=[(2,4), (2,6)])
Returns:None. The spec is updated
coremltools.models.neural_network.flexible_shape_utils.can_allow_multiple_input_shapes(spec)

Examines a model specification and determines if it can compute results for more than one output shape.

Parameters:spec – MLModel The protobuf specification of the model.
Returns:Bool Returns True if the model can allow multiple input shapes, False otherwise.
coremltools.models.neural_network.flexible_shape_utils.get_allowed_shape_ranges(spec)

For a given model specification, returns a dictionary with a shape range object for each input feature name.

coremltools.models.neural_network.flexible_shape_utils.set_multiarray_ndshape_range(spec, feature_name, lower_bounds, upper_bounds)

Annotate an input or output MLMultiArray feature in a Neural Network spec to accommodate a range of shapes. This is different from “update_multiarray_shape_range”, which works with rank 5 SBCHW mapping.

Parameters:
  • spec – MLModel The MLModel spec containing the feature
  • feature_name – str The name of the feature for which to add shape range information. If the feature is not found in the input or output descriptions then an exception is thrown
  • lower_bounds – List[int] list of integers specifying the lower bounds of each dimension. Length must be same as the rank (length of shape) of the feature_name.
  • upper_bounds – List[int] list of integers specifying the upper bounds of each dimension. -1 corresponds to unbounded range. Length must be same as the rank (length of shape) of the feature_name.

Examples

>>> import coremltools
>>> from coremltools.models.neural_network import flexible_shape_utils
>>> spec = coremltools.utils.load_spec('mymodel.mlmodel')
>>> # say, the default shape of "my_multiarray_featurename" is (2,3)
>>> flexible_shape_utils.set_multiarray_ndshape_range(spec, feature_name='my_multiarray_featurename', lower_bounds=[1,2], upper_bounds=[10,-1])
Returns:None. The spec is updated
coremltools.models.neural_network.flexible_shape_utils.update_image_size_range(spec, feature_name, size_range)

Annotate an input or output Image feature in a Neural Network spec to to accommodate a range of image sizes

Parameters:
  • spec – MLModel The MLModel spec containing the feature
  • feature_name – str The name of the Image feature for which to add shape information. If the feature is not found in the input or output descriptions then an exception is thrown
  • size_range – NeuralNetworkImageSizeRange A NeuralNetworkImageSizeRange object with the populated image size range information.

Examples

>>> import coremltools
>>> from coremltools.models.neural_network import flexible_shape_utils
>>> spec = coremltools.utils.load_spec('mymodel.mlmodel')
>>> img_size_ranges = flexible_shape_utils.NeuralNetworkImageSizeRange()
>>> img_size_ranges.add_height_range(64, 128)
>>> img_size_ranges.add_width_range(128, -1)
>>> flexible_shape_utils.update_image_size_range(spec, feature_name='my_multiarray_featurename', size_range=img_size_ranges)
Returns:None. The spec object is updated
coremltools.models.neural_network.flexible_shape_utils.update_multiarray_shape_range(spec, feature_name, shape_range)

Annotate an input or output MLMultiArray feature in a Neural Network spec to accommodate a range of shapes

Parameters:
  • spec – MLModel The MLModel spec containing the feature
  • feature_name – str The name of the feature for which to add shape range information. If the feature is not found in the input or output descriptions then an exception is thrown
  • shape_range – NeuralNetworkMultiArrayShapeRange A NeuralNetworkMultiArrayShapeRange object with the populated shape range information. The shape_range object must either contain only shape information for channel or channel, height and width. If the object is invalid then an exception is thrown

Examples

>>> import coremltools
>>> from coremltools.models.neural_network import flexible_shape_utils
>>> spec = coremltools.utils.load_spec('mymodel.mlmodel')
>>> shape_range = flexible_shape_utils.NeuralNetworkMultiArrayShapeRange()
>>> shape_range.add_channel_range((1, 3))
>>> shape_range.add_width_range((128, 256))
>>> shape_range.add_height_range((128, 256))
>>> flexible_shape_utils.update_multiarray_shape_range(spec, feature_name='my_multiarray_featurename', shape_range=shape_range)
Returns:None. The spec is updated