API Reference: Spec

masterful.spec.create_model_and_data_specs

masterful.spec.create_model_and_data_specs(model, dataset, task, image_range, num_classes, sparse, from_logits)

Convenience function to create both model and data specs.

For most users, this is the key function to generate the necessary specifications of a model and data. Most specifications are introspected from the model and dataset. The specifications that cannot be introspected are specified as arguments.

Example

>>> model_spec, data_spec = masterful.spec.create_model_and_data_specs(
    task=masterful.spec.Task.CLASSIFICATION,
    model=model,
    dataset=train_dataset,
    image_range=masterful.spec.ImageRange.ZERO_255,
    num_classes=10,
    from_logits=True,
    sparse=False)
Parameters

  • model (keras.engine.training.Model) – The model to introspect.

  • dataset (tensorflow.python.data.ops.dataset_ops.DatasetV2) – The dataset to introspect.

  • task (masterful.spec.Task) – The computer task for this model.

  • image_range (masterful.spec.ImageRange) – The valid range of image pixels.

  • num_classes (int) – The number of possible classes found in the groundtruth data.

  • sparse (bool) – True if the ground truth classes are encoded in sparse format. Note that Masterful works best with dense labels, with the setting sparse=False. The data can be transformed trivially from sparse to dense with the tf.one_hot operation.

  • from_logits (bool) – True is the model’s predictions are not activated by softmax or sigmoid.

Returns

A tuple of the specification for the model, and the specification for the data.

Return type

Tuple[masterful.spec.ModelSpec, masterful.spec.DataSpec]

masterful.spec.ModelSpec

class masterful.spec.ModelSpec(task=None, num_classes=None, num_objects=None, detection_tensor_format=None, detection_origin=None, detection_bbox_units=None, detection_bbox_format=None, detection_anchor_format=None, range=None, height=None, width=None, channels=None, channels_last=None, from_logits=None)

Holds specifications for a model.

In general, instances of this object do not need to be created directly. Instead, see create_model_and_data_specs().

Parameters

  • task (masterful.spec.Task) – The type of computer vision task that the model predicts. Enumerated in masterful.Task.

  • model – A model to introspect.

  • image_range – A valid range of pixel values, enumerated in masterful.spec.ImageRange.

  • num_classes (int) – The number of types of classes predicted.

  • from_logits (bool) – Whether the model’s classification prediction is activated with binarycrossenropy/categoricalcrossentropy, or if there is no activation and a loss function like tf.keras.losses.CategoricalCrossEntropy should be instantiated with the from_logits=True.

  • num_objects (int) –

    Only applicable if task is INSTANCE_SEGMENTATION, DETECTION, LOCALIZATION, or KEYPOINT_DETECTION.

    The max number of masks or bounding boxes that can be predicted per image.

  • detection_tensor_format (masterful.spec.DetectionTensorFormat) – Only applicable if task is DETECTION, LOCALIZATION, or KEYPOINT_DETECTION. Output format for a detectors regression and classification tasks, enumerated in masterful.spec.spec.DetectionTensorFormat.

  • detection_origin (str) – Only applicable if task is DETECTION, LOCALIZATION, or KEYPOINT_DETECTION.

  • detection_bbox_units (str) – Only applicable if task is DETECTION, LOCALIZATION, or KEYPOINT_DETECTION.

  • detection_bbox_format (str) – Only applicable if task is DETECTION, LOCALIZATION, or KEYPOINT_DETECTION.

  • detection_anchor_format (str) – Only applicable if task is DETECTION, LOCALIZATION, or KEYPOINT_DETECTION.

  • range (masterful.spec.ImageRange) –

  • height (int) –

  • width (int) –

  • channels (str) –

  • channels_last (bool) –

Return type

None

classmethod from_model(task, model, image_range, num_classes, from_logits, num_objects=None, detection_tensor_format=None, detection_origin=None, detection_bbox_units=None, detection_bbox_format=None, detection_anchor_format=None)

Create ModelSpec by introspecting model where possible.

Parameters

  • task (masterful.spec.Task) –

  • model (keras.engine.training.Model) –

  • image_range (masterful.spec.ImageRange) –

  • num_classes (int) –

  • from_logits (bool) –

  • num_objects (Optional[int]) –

  • detection_tensor_format (Optional[masterful.spec.DetectionTensorFormat]) –

  • detection_origin (Optional[str]) –

  • detection_bbox_units (Optional[str]) –

  • detection_bbox_format (Optional[str]) –

  • detection_anchor_format (Optional[str]) –

masterful.spec.DataSpec

class masterful.spec.DataSpec(task=None, num_classes=None, num_objects=None, detection_tensor_format=None, detection_origin=None, detection_bbox_units=None, detection_bbox_format=None, detection_anchor_format=None, range=None, height=None, width=None, channels=None, channels_last=None, sparse=None)

Holds specifications for data used to train a model.

In general, instances of this object do not need to be created directly. Instead, see create_model_and_data_specs().

Parameters

  • task (masterful.spec.Task) –

  • num_classes (int) –

  • num_objects (int) –

  • detection_tensor_format (masterful.spec.DetectionTensorFormat) –

  • detection_origin (str) –

  • detection_bbox_units (str) –

  • detection_bbox_format (str) –

  • detection_anchor_format (str) –

  • range (masterful.spec.ImageRange) –

  • height (int) –

  • width (int) –

  • channels (str) –

  • channels_last (bool) –

  • sparse (bool) –

Return type

None

classmethod from_dataset(task, dataset, image_range, num_classes, sparse, num_objects=None, detection_tensor_format=None, detection_origin=None, detection_bbox_units=None, detection_bbox_format=None, detection_anchor_format=None)

Create DataSpec by introspecting tf.data.Dataset where possible.

Parameters

  • task (masterful.spec.Task) –

  • dataset (tensorflow.python.data.ops.dataset_ops.DatasetV2) –

  • image_range (masterful.spec.ImageRange) –

  • num_classes (int) –

  • sparse (bool) –

  • num_objects (Optional[int]) –

  • detection_tensor_format (Optional[masterful.spec.DetectionTensorFormat]) –

  • detection_origin (Optional[str]) –

  • detection_bbox_units (Optional[str]) –

  • detection_bbox_format (Optional[str]) –

  • detection_anchor_format (Optional[str]) –

masterful.spec.Task

class masterful.spec.Task(value)

Bases: enum.Enum

An enum to semantically specify a model’s use case.

Parameters

value – Overriden from enum.Enum. Returns the member of this enum from the corresponding value.

CLASSIFICATION

Normal classification task like Alexnet on Imagenet.

BINARY_CLASSIFICATION

Binary classification task.

MULTILABEL_CLASSIFICATION

Multi-label classification task.

DETECTION

Object detection (localization + classification) task.

LOCALIZATION

Object localization task.

SEMANTIC_SEGMENTATION

Semantic segmentation task.

INSTANCE_SEGMENTATION

Instance segmentation task.

KEYPOINT_DETECTION

Keypoint detection task.

masterful.spec.ImageRange

class masterful.spec.ImageRange(value)

Bases: enum.Enum

An enum to model the image input ranges Masterful supports.

Parameters

value – Overriden from enum.Enum. Returns the member of this enum from the corresponding value.

ZERO_ONE

Image range is [0,1].

NEG_ONE_POS_ONE

Image range is [-1, 1].

ZERO_255

Image range is [0,255].

IMAGENET_CAFFE_BGR

Image is in BGR channel format, and each channel has been zero-centered around the Imagenet mean, without scaling.

IMAGENET_TORCH

Image pixels were scaled to [0,1], then each channel was zero-centered around the Imagenet mean.

CIFAR10_TORCH

Image pixels were scaled to [0,1], then each channel was zero-centered around the CIFAR10 mean.

masterful.spec.DetectionTensorFormat

class masterful.spec.DetectionTensorFormat(value)

Bases: enum.Enum

An enum to specify detection label and prediction formats.

Parameters

value – Overriden from enum.Enum. Returns the member of this enum from the corresponding value.

SINGLE_TENSOR

For detectors that output a tensor of shape (N, M, 4+C+X). 4 represents the bounding box info in yxyx format. C is the number of possible classes. X holds other information such as ignore or objectness.

TRIPLE_TENSOR

For detectors that output multiple tensors. The first tensor represents the boxes and is shape NM4 or NM5, representing bounding boxes and optionally an ignore or objectness value. The second tensor represents the classifications and is shape NMC or (N, M, C+1) represending the one-hot classification predictions and optionally an ignore or objectness value. The third tensor holds other metadata and is of shape NMX.

FIZYR_KERAS_RETINANET

For the Fizyr Keras Retinanet implementation. Works with these built-in loss functions and the Masterful loss wrapper, which shifts the anchor box target generation from a preprocessing step on CPU to a layerized step that runs on GPU.