The Capsule Class

Introduction

The Capsule class provides information to the application about what a capsule is and how it should be run. Every capsule defines a Capsule class that extends BaseCapsule in its capsule.py file.

from vcap import (
    BaseCapsule,
    NodeDescription,
    options
)

class Capsule(BaseCapsule):
    name = "detector_person"
    version = 1
    stream_state = StreamState
    input_type = NodeDescription(size=NodeDescription.Size.NONE),
    output_type = NodeDescription(
        size=NodeDescription.Size.ALL,
        detections=["person"])
    backend_loader = backend_loader_func
    options = {
        "threshold": options.FloatOption(
            default=0.5,
            min_val=0.1,
            max_val=1.0)
    }
class BaseCapsule(capsule_files: Dict[str, bytes], inference_mode=True)

An abstract base class that all capsules must subclass. Defines the interface that capsules are expected to implement.

A class that subclasses from this class is expected to be defined in a capsule.py file in a capsule.

Parameters
  • capsule_files – A dict of {“file_name”: FILE_BYTES} of the files that were found and loaded in the capsule

  • inference_mode – If True, the model will be loaded and the backends will start for it. If False, the capsule will never be able to run inference, but it will still have it’s various readable attributes.

abstract static backend_loader(capsule_files: Dict[str, bytes], device: str) → vcap.backend.BaseBackend

A function that creates a backend for this capsule.

Parameters
  • capsule_files – Provides access to all files in the capsule. The keys are file names and the values are bytes.

  • device – A string specifying the device that this backend should use. For example, the first GPU device is specified as “GPU:0”.

property description

A human-readable description of what the capsule does.

property device_mapper

A device mapper contains a single field, filter_func, which is a function that takes in a list of all available device strings and returns a list of device strings that are compatible with this capsule.

property input_type

Describes the types of DetectionNodes that this capsule takes in as input.

property name

The name of the capsule. This value uniquely defines the capsule and cannot be shared by other capsules.

By convention, the capsule’s name is prefixed by some short description of the role it plays (“detector”, “recognizer”, etc) followed by the kind of data it relates to (“person”, “face”, etc) and, if necessary, some differentiating factor (“fast”, “close_up”, “retail”, etc). For example, a face detector that is optimized for quick inference would be named “detector_face_fast”.

property options

A list of zero or more options that can be configured at runtime.

property output_type

Describes the types of DetectionNodes that this capsule produces as output.

property stream_state

(Optional) An instance of this object will be created for every new video stream that a capsule is run on, and de-initialized when that stream is deleted. It is intended to be overridden by capsules that have stateful operations across a single stream.

property version

The version of the capsule.

When should you bump the version of a capsule? When:
  • You’ve changed the usage of existing capsule options

  • You’ve changed the model or algorithm

  • You’ve changed the input/output node descriptions

When shouldn’t you bump the version of a capsule? When:
  • You only did code restructuring

  • You’ve updated the capsule to work with a newer API version

  • You’ve added (but not removed or changed previous) capsule options

In summary, the version is most useful for differentiating a capsule from its previous versions.