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:
./Store.exe --mode server --ip 192.168.0.1
Name
Store
State
"State" is the top level item.
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 |
|
ConnectedClients
Returns an array with all currently connected services (services that currently respond to heartbeats).
Response
STRING ARRAY |
|
DefaultShow
Returns the name of the currently open show.
Response
STRING |
|
Shows
Returns an array of all shows available on this store (reads the files available on disk)
Response
OBJECT ARRAY |
|
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 |
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 |
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 |
|
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 |
|
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 |
|
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: |
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.