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.