Capsules

A capsule is a single file with a .cap file extension. It contains the code, metadata, model files, and any other files the capsule needs to operate. See the Introduction to Capsules for more information.

API Methods

BrainFrameAPI.get_capsule(name, timeout=30) → brainframe.api.bf_codecs.capsule_codecs.Capsule
Parameters

  • name – The name of the capsule to get

  • timeout – The timeout to use for this request

Returns

Capsule with the given name

BrainFrameAPI.get_capsules(timeout=30) → List[brainframe.api.bf_codecs.capsule_codecs.Capsule]
Parameters

timeout – The timeout to use for this request

Returns

All available capsules

BrainFrameAPI.get_capsule_option_vals(capsule_name, stream_id=None, timeout=30) → Dict[str, object]

Gets the current values for every capsule option. See the documentation for the CapsuleOption codec for more info about global and stream level options and how they interact.

Parameters

  • capsule_name – The capsule to find options for

  • stream_id – The ID of the stream. If this value is None, then the global options are returned for that capsule

  • timeout – The timeout to use for this request

Returns

A dict where the key is the option name and the value is the option’s current value

BrainFrameAPI.set_capsule_option_vals(*, capsule_name, stream_id=None, option_vals: Dict[str, object], timeout=30)

Sets option values for a capsule.

Parameters

  • capsule_name – The name of the capsule whose options to set

  • stream_id – The ID of the stream, if these are stream-level options. If this value is None, then the global options are set

  • option_vals – A dict where the key is the name of the option to set, and the value is the value to set that option to

  • timeout – The timeout to use for this request

BrainFrameAPI.patch_capsule_option_vals(*, capsule_name, stream_id=None, option_vals: Dict[str, object], timeout=30)

Patches option values for a capsule. Only the provided options are changed. To unset an option, provide that option with a value of None.

Parameters

  • capsule_name – The name of the capsule whose options to set

  • stream_id – The ID of the stream, if these are stream-level options. If this value is None, then the global options are set

  • option_vals – A dict where the key is the name of the option to set, and the value is the value to set that option to

  • timeout – The timeout to use for this request

BrainFrameAPI.is_capsule_active(capsule_name, stream_id=None, timeout=30) → bool

Returns True if the capsule is active. If a capsule is not marked as active, it will not run. Like capsule options, this can be configured globally and on a per-stream level.

Parameters

  • capsule_name – The name of the capsule to get activity for

  • stream_id – The ID of the stream, if you want the per-stream active setting

  • timeout – The timeout to use for this request

Returns

True if the capsule is active

BrainFrameAPI.set_capsule_active(*, capsule_name, stream_id=None, active: Optional[bool], timeout=30)

Sets whether or not the capsule is active. If a capsule is active, it will be run on frames.

Parameters

  • capsule_name – The name of the capsule to set activity for

  • stream_id – The ID of the stream, if you want to set the per-stream active setting

  • active – True if the capsule should be set to active

  • timeout – The timeout to use for this request

Data Structures

class Capsule(name: str, version: int, description: str, input_type: brainframe.api.bf_codecs.capsule_codecs.NodeDescription, output_type: brainframe.api.bf_codecs.capsule_codecs.NodeDescription, capability: brainframe.api.bf_codecs.capsule_codecs.NodeDescription, options: Dict[str, brainframe.api.bf_codecs.capsule_codecs.CapsuleOption])

Metadata on a loaded capsule.

capability: NodeDescription

A NodeDescription which describes what this capsule does to its input. It is the difference between the input and output NodeDescriptions. This field is useful for inspecting a capsule to find what it can do.

description: str

A human-readable description of what the capsule does

input_type: NodeDescription

Describes the type of inference data that this capsule takes as input

name: str

The name of the capsule

options: Dict[str, CapsuleOption]

A dict describing the configurable options of this capsule

output_type: NodeDescription

Describes the type of inference data that this capsule produces

version: int

The capsule’s version

class CapsuleOption(type: brainframe.api.bf_codecs.capsule_codecs.CapsuleOption.Type, default: Any, constraints: dict, description: str)

A single configuration option for a capsule. Defines what type of option it is and its potential values.

There are two kinds of capsule options. Stream capsule options apply only to the stream they are attached to. Global capsule options apply to all streams, but are overridden by stream capsule options.

class Type(value)

The data type of a capsule option

classmethod values()
constraints: dict

Describes the range of valid values for this option. The content of this dict depends on the type field.

OptionType.FLOAT:

max_val: The maximum valid float value

min_val: The minimum valid float value

OptionType.INT:

max_val: The maximum valid int value

min_val: The minimum valid int value

OptionType.ENUM:

choices: A list of strings. The option’s value must be one of these strings.

OptionType.BOOL:

This object has no constraints.

default: Any

The default value for this option

description: str

A human-readable description of the capsule’s capabilities

type: Type

The data type of this option’s value

class NodeDescription(size: brainframe.api.bf_codecs.capsule_codecs.NodeDescription.Size, detections: List[str], attributes: Dict[str, List[str]], encoded: bool, tracked: bool, extra_data: List[str])

A description of a DetectionNode, used by capsules to define what kinds of inputs and outputs a capsule uses.

class Size(value)

Describes the amount of DetectionNodes a capsule takes as input or provides as output.

ALL = 'all'

Input: The capsule takes all instances of a class as input, like for a tracker.

Output: The capsule provides all instances of a class as output, like for a detector.

NONE = 'none'

Input: The capsule takes nothing as input, like for an object detector.

Output: Capsules cannot have a NONE output.

SINGLE = 'single'

Input: The capsule takes a single DetectionNode as input, like for a classifier.

Output: The capsule provides a single modified DetectionNode as output, like for a classifier.

classmethod values()
attributes: Dict[str, List[str]]

Key-value pairs whose key is the classification type and whose value is a list of possible attributes. A DetectionNode that meets this description must have a classification for each classification type listed here.

detections: List[str]

A list of detection class names, like “person” or “vehicle”. A DetectionNode that meets this description must have a class name that is present in this list.

encoded: bool

If True, the DetectionNode must be encoded to meet this description

extra_data: List[str]

A list of keys in a NodeDescription’s extra_data. A DetectionNode that meets this description must have extra data for each name listed here.

size: Size

Describes the amount of DetectionNodes the node either takes in as input or provides as output

tracked: bool

If True, the DetectionNode must be tracked to meet this description