Skip to main content
Skip table of contents

Pixotope Store - API

Description

Pixotope Store is a Pixotope Service which exists only once per network. It can be considered the main backend component of a Pixotope Network, even though states can also live outside of the Store itself.

List of responsibilities

  • Storing global data (such as Cameras, VideoIOs, Show Settings, etc) in its State (meaning it is per Show)

  • Storing States by other services

    • The State of Store is very malleable and can fit any custom data you want to put into it

  • Keeping memory of all states (its own and all service states) in .pxshow files. This way you can switch between complete sets of states (Shows)

  • Exposing backend data (that is within its domain) to anyone interested

    • For example showing which clients are connected to the network, or what shows are available

  • Exposing backend functionality (that is within its domain) to anyone interested

    • For example giving the possibility to add a camera, or change a show

Store can run in two modes, server or standalone. The mode is passed to Store on startup, along with an optional IP for broadcasting on, like so:

BASH
./Store.exe --mode server --ip 192.168.0.1

Name

Store

State

"State" is the top level item.

TYPESCRIPT
export type DXType = "11" | "12";
export type IOType = "Input" | "Output";
export type InputType = "AJA" | "File" | "BMD" | "NDI";
export type KeyerModel = "ProjectionKeyer" | "MahalKeyer";
export type CompositingColorSpaceType = "Video" | "Linear";
export type UnitsType = "CM" | "Inches";
export type FormatType = "rgb8" | "yuv10" | "rgb10";

export interface ChromaKeyShaderParams {
  BackgroundPicks: [[number, number, number]];
  // eslint-disable-next-line no-inline-comments
  EnableCleanPlate: boolean;
  ForegroundThreshold: number;
  BackgroundThreshold: number;
  SaturationThreshold: number;
  ShadowStrength: number;
  ShadowContrast: number;
  EdgeLumaCorrection: number;
  DespillStrength: number;
  DespillCutoff: number;
  DespillHue: number;
  MaskGamma: number;
  MaskGain: number;
  LumaKeyIntensity: number;
  ErodeSize: number;
  BlurStrength: number;
  BlurSize: number;
  ColorKeyIntensityR: number;
  ColorKeyIntensityG: number;
  ColorKeyIntensityB: number;
  DetailEnhancement: number;
  Denoise: number;
}

export interface CameraSpecific {
  FilmbackWidth: number;
  FilmbackHeight: number;
  Aperture: number;
  EnableDOF: boolean;
  DistortionModel: string;
  EnableFilmback: boolean;
}
export interface InputConfig {
  ID: string; // null when camera
  TrackingProtocol: string;
  CameraSpecific: null | CameraSpecific; // null only when object
  Source: {
    Type: string;
    Value: {
      IP: string;
      Port: number;
    };
  };
  LengthUnits: string;
  AngleUnits: string;
  AxisPositives: {
    X: string;
    Y: string;
    Z: string;
  };
  RotationPositives: {
    Pan: string;
    Tilt: string;
    Roll: string;
  };
}

export interface Vector {
  X: number;
  Y: number;
  Z: number;
}

export const zeroVector = {
  X: 0,
  Y: 0,
  Z: 0,
};
export interface EulerAngles {
  Pan: number;
  Tilt: number;
  Roll: number;
}

export const zeroEulerAngles = {
  Pan: 0,
  Tilt: 0,
  Roll: 0,
};

export interface LensFileConfig {
  UseLensFile: boolean;
  LensFilePath: string;
  ZoomEncoderOut: number;
  ZoomEncoderIn: number;
  FocusEncoderNear: number;
  FocusEncoderFar: number;
  EnableDOF: boolean;
  EnableDistortion: boolean;
  EnableNodal: boolean;
  EnableFOV: boolean;
  EnableCenterOffset: boolean;
}
export interface LensOffsets {
  FieldOfView: number;
  FocusDistance: number;
  Aperture: number;
  CX: number;
  CY: number;
  NodalX: number;
  ShowCrosshair: boolean;
  K1: number;
  K2: number;
}
export interface ChainOutput {
  Name: string; // Can we omit this??
  IP: string;
  Port: number;
  TrackingProtocol: string;
}

export interface NoMountOffset {
  Type: "No mount setup";
  Value: {
    GlobalPosition: Vector;
    GlobalRotation: Vector;
    CameraRotation: EulerAngles;
  };
}

export interface ObjectOffsets {
  Type: "Object offsets";
  Value: {
    GlobalPosition: Vector;
    GlobalRotation: Vector;
  };
}

export interface TripodOffsets {
  Type: "Tripod/Dolly/Crane";
  Value: {
    GlobalPosition: Vector;
    GlobalRotation: Vector;
    CameraRotation: EulerAngles;
    MountedPosition: Vector;
    Height: number;
  };
}

export interface CraneOffsets {
  Type: "Mechanical camera crane";
  Value: {
    GlobalPosition: Vector;
    GlobalRotation: Vector;
    CameraRotation: EulerAngles;
    MountedPosition: Vector;
    Height: number;
    MainArmLength: number;
    ExtenderLength: number;
    DropLength: number;
    SwingOffset: number;
    ElevateOffset: number;
    InvertSwing: boolean;
    InvertElevate: boolean;
  };
}

export interface TimecodeSelection {
  1: string;
  2: string;
  3: string;
  4: string;
}

export const defaultTimeCodeSelection = {
  1: "Disabled",
  2: "Disabled",
  3: "Disabled",
  4: "Disabled",
};
type FrameMatchingType = "BufferSize" | "Timecode";
export interface Chain {
  Name: string;
  Ancillary:
    | {
        Fingerprint: string;
        Delay: number;
        VideoInputDelay: number;
        VideoOutputDelay: number;
        CameraType: string | null;
        AssignedCTS: string;
        Timecode: TimecodeSelection;
        FrameMatchingMethod: FrameMatchingType;
      }
    | { AssignedGroup: string; Delay: number };
  Input: InputConfig;
  PositionOffsets: NoMountOffset | ObjectOffsets | TripodOffsets | CraneOffsets;
  LensOffsets: null | LensOffsets;
  LensFileConfig: null | LensFileConfig;
  Outputs: { [key: string]: ChainOutput };
}

export interface Camera extends Chain {
  Ancillary: {
    Fingerprint: string;
    Delay: number;
    VideoInputDelay: number;
    VideoOutputDelay: number;
    CameraType: string;
    AssignedCTS: string;
    Timecode: TimecodeSelection;
    FrameMatchingMethod: FrameMatchingType;
  };
}
export interface ObjectTrackerGroup extends Chain {
  Ancillary: {
    Fingerprint: string;
    Delay: number;
    VideoInputDelay: number;
    VideoOutputDelay: number;
    CameraType: null;
    AssignedCTS: string;
    Timecode: TimecodeSelection;
    FrameMatchingMethod: FrameMatchingType;
  };
  LensOffsets: null;
  LensFileConfig: null;
}

export interface ObjectTracker extends Chain {
  Ancillary: {
    AssignedGroup: string;
    Delay: number;
  };
  LensOffsets: null;
  LensFileConfig: null;
}
export interface AudioSelection {
  Enabled: boolean;
  Delay: number;
}
export interface VideoIO {
  Fingerprint: string;
  IOType: IOType;
  Name: string;
  // eslint-disable-next-line no-inline-comments
  Camera: string; // cameraID or undefined if media input
  VideoFormat: string;
  ColorProfile: string;
  ColorSpace: string;
  Rgbrange: boolean;
  Format: FormatType;
  InputType: InputType;
  Type: string;
  BufferSize: number;
  Parent: string;
  Audio: AudioSelection;
  Chromakey: {
    Enabled: boolean;
    OutputKey: boolean;
    KeyerModel: KeyerModel;
    ShaderParams: null | ChromaKeyShaderParams;
  };
}

export interface State {
  State: {
    General: {
      DXMode: DXType;
      EditorStartupOptions: string;
      CompositingColorSpace: CompositingColorSpaceType;
    };
    Defaults: {
      Units: UnitsType;
      VideoInputFormat: string;
      VideoOutputFormat: string;
      Type: InputType;
      ColorProfile: string;
      ColorSpace: string;
    };
    Cameras: Record<string, Camera>;
    ObjectTrackerGroups: Record<string, ObjectTrackerGroup>;
    ObjectTrackers: Record<string, ObjectTracker>;
    VideoIO: Record<string, VideoIO>;
    Projects: string[];
    Version: string;
  };
}

Non-state values

Use a Get-request to access these values.

AvailablePixotopeNetworks

Returns an array of active Stores (and so Pixotope Networks, as there is one Store per Pixotope Network) that are broadcasting themselves. This is useful when you want to connect to another Pixotope Network.

Response

OBJECT ARRAY

[{"name\":"DESKTOP-GO883O4","ip":"192.168.0.190","port":16206},…]

ConnectedClients

Returns an array with all currently connected services (services that currently respond to heartbeats).

Response

STRING ARRAY

[{"Name":"Machine1-CTS", "Role":"CTS"},…]

DefaultShow

Returns the name of the currently open show.

Response

STRING

"DefaultShow"

Shows

Returns an array of all shows available on this store (reads the files available on disk)

Response

OBJECT ARRAY

["DefaultShow",…]

RPC

ChangeShow

Changes the open show. This can be a new one.

Parameters

ShowName

STRING

Name of show to change to

CreateShow

Same as ChangeShow, but also sets the project path from the provided argument.

Parameters

ShowName

STRING

Name of new show

Project

STRING

Path of .uproject file of the linked project

CreateShowWithTemplate

Same as CreateShow but also copies all files from the "Template"-location to the "Project" location.

Parameters

ShowName

STRING

Name of new show

Project

STRING

Path of folder the template project should be copied to (linked project)

Template

STRING

Path of .uproject file of the template project

RenameShow

Renames a show.

Parameters

ShowName

STRING

Name of show to rename

NewShowName

STRING

New name

DuplicateShow

Duplicates a show.

Parameters

ShowName

STRING

Name of show to duplicate

DeleteShow

Deletes the show from disk.

The current show can not be deleted.

Parameters

ShowName

STRING

Name of show to delete


AddCamera

Creates a new camera system object under a unique identifier.

Use AddDefaultCamera when possible.

Parameters

Name

STRING

Name of the new camera system

Fingerprint

STRING

Unique identifier of the owner

ObjectState

OBJECT

Camera object

AddDefaultCamera

Same as AddCamera, but the Camera/Chain-object is created based on defaults. This is the most common way of creating a camera.

Parameters

Name

STRING

Name of the new camera system

Fingerprint

STRING

Unique identifier of the owner

DuplicateCamera

Duplicates the camera system with the specified name and updates the fingerprint of the duplicate.

Parameters

Camera

STRING

Name of camera system to duplicate

Fingerprint

STRING

Unique identifier of the new owner

AddVideoIO

Adds a new VideoIO object.

Parameters

ObjectState

OBJECT

VideoIO object

Fingerprint

STRING

Unique identifier of the new owner

AddDefaultObjectTrackerGroup

Creates a new Object Tracker Group object under a unique identifier.

Parameters

Name

STRING

Name of the new object tracker group

Fingerprint

STRING

Unique identifier of the owner

DuplicateObjectTrackerGroup

Same as DuplicateCamera but for ObjectTrackerGroup.

Parameters

Group

STRING

Name of the new object tracker group to duplicate

Fingerprint

STRING

Unique identifier of the owner

AddDefaultObjectTracker

Creates a new Tracker object under the provided Group ID.

Parameters

Group

STRING

Name of the object tracker group the object tracker should be added to

Name

STRING

Name of the new object tracker

CreateObjectWithUniqueID

Used for creating objects under unique identifiers in the database, used mostly internally (for example in AddCamera).

Parameters

Position

STRING

Position

ObjectState

OBJECT

ObjectState

RouteVideoIO

Routes a VideoIO object to the designated Pipeline (VideoIO service on a specific machine).

If the VideoIO object is a camera, it also routes tracking information using the IP.

Parameters

VideoIO

OBJECT

VideoIO object

Pipeline

STRING

Name of the VideoIO service (on a specific machine) the videoIO object should be routed to

Video

STRING

Input/output address to use (for example sdi1 if using AJA or BMD)

IP

STRING

IP address of the target machine, in case the VideoIO is a Camera and tracking data needs to be sent.

DeRouteVideoIO

Removes a VideoIO routing from a Pipeline (VideoIO service).

Parameters

VideoIO

OBJECT

VideoIO object

Pipeline

STRING

Name of the VideoIO service the videoIO object is routed to


GetStateForShow

Will return the complete state of a specific service and show. This is useful when importing settings from another show and similar.

To get the current show, use a normal Get.

Parameters

Service

STRING

Name of the service

ShowName

STRING

Name of the show

GetAllStatesForShow

Same as GetStateForShow, but returns the states of all services

Parameters

ShowName

STRING

Name of the show

GetAllStates

Same as GetAllStatesForShow, using the current show.

GetShowFile

Gets a complete show DB file in binary format.

Parameters

ShowName

STRING

Name of the show


TargetRole

Relays an RPC message to all connected instances of a specific service (or all services).

Parameters

Topic

OBJECT

Topic of the message you want to relay

In the "Target" field you specify the services you want to target. Possible values: "DataHub" | "Store" | "DirectorAPI" | "VideoIO" | "Tracking" | "Director" | "Engine" | "All"

Message

OBJECT

Message you want to relay

Examples

I want to get the projects associated with the current show

  • I send a GET-request with the target "Store" and name "State.Projects"

I want to change the setting of a camera on the store for the current show

  • I send a SET-request with the target "Store" and name "State.Cameras.MyCameraID.MyCameraSetting" and the value "MyNewCameraSettingValue".

I want to see what shows are available

  • I send a GET-request with the target "Store" and name "Shows"

I want to set what shows are available

  • This is not possible via this messaging protocol, "Shows" is inferred data, based on what exists on the store PC in a specified folder, SET is not valid in this context.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.