Open Spherical Camera API Version 1.1.2

(1)

OPEN SPHERICAL CAMERA

v1.1.2

20/07/2016

(2)

SUMMARY

MANUFACTURER GUIDE Introduction & Feedback Overview Discovery OSC Protocol a. info b. state c. commands Error Handling API SPECIFICATION Overview Commands I. System & Connection a. camera.startSession b. camera.closeSession c. camera.updateSession d. camera.wifiMode II. Recording & Shooting a. camera.takePicture b. camera._startRecording c. camera._stopRecording d. paramState III. Navigate & Get Information a. camera._getAttributes b. camera._listDirectory c. camera._getStreamUrl IV. Read, Edit & Delete a. camera._readFile b. camera._writeFile (unactive) c. camera.delete V. Metadata Commands a. camera.getMetadata b. camera._setMetadata c. camera._patchMetadata VI. Image Commands a. camera.getImage b. camera._getImagePreview c. camera.listImages VII. Get & Set Options

(3)

b. camera.setOptions c. Options d. Appendix Revision History

(4)

MANUFACTURER GUIDE

(5)

Introduction & Feedback

Welcome to the Giroptic Open Spherical Camera API. Your feedback helps us shape the development of the API. This preview includes the Manufacturer Guide and API Specification. Download PDFs of the latest revision of both documents at the links below: http://dev.360.tv/

We look forward to hearing your feedback on how we can improve the OSC API Specification and Manufacturer Guide. Whether you've encountered engineering pain points, confusing documentation, or unexpected behavior, please let us know. Send any questions or comments you may have to

[email protected]

Overview

This guide provides spherical camera API implementation guidance to manufacturers of cameras with builtin wifi. Please refer to OSC API Specification for the full set of commands.

(6)

Discovery

Discovery flow works as follows: the camera brings up a password protected WiFi network to signal its existence, the client can scan for such networks, display them to the user, and allow the user to connect to the right one by entering the correct password at least once.

It consists of two parts for the camera implementation: defining a specific SSID to allow clients to find and connect to the right password protected network, and using default port 80 for HTTP.

SSID and password SSID format:

[Camera name].OSC

The wifi SSID shall start with a human readable name (up to 20 characters), following by delimiter ‘.’ and “OSC” (OSC stands for “Open Spherical Camera”, the protocol used for communications between clients and cameras). The camera name contains manufacturer selected user friendly name. It is HIGHLY RECOMMENDED to add some entropy to the end of the name to prevent name collisions. For example, “VendorCamera123.OSC”, where “123” is used to differentiate between the same type of cameras nearby.

The wifi MUST be protected with WPA2 PSK. The wifi password MUST be at least 8 characters long and it can contain letters, numbers, symbols, but no spaces. It can be changed only when the camera is connected to the phone. Once it is changed, the camera will be disconnected and needs to be reconnected using the new password.

The camera MUST provide a reset mechanism in case the password is forgotten, e.g. a reset button in the camera to restore the default password.

IP address and port:

The camera’s IP address can be obtained from the wifi connection on the client side. For port, please use default port 80 for HTTP (port for update can be obtained from endpoints in /osc/info).

(7)

OSC Protocol

After the camera has been discovered, communication between the client and the camera is directly over the local network. All the following APIs are HTTP 1.1 based. API requests may be GET or POST requests. Basically, the camera needs to implement a HTTP server for OSC protocol.

(8)

a. info

Description

The /osc/info API returns basic information about the camera and functionality it supports.

Input

No input.

Output

Name

Type

Description

manufacturer String The camera manufacturer. model String The camera model.

description String Description of the camera model. serialNumber String Serial number.

firmwareVersion String Current firmware version. hardwareVersion String Current hardware version.

supportUrl String URL for the camera’s support webpage. gps Boolean True if the camera has GPS.

gyro Boolean True if the camera has gyroscope.

uptime Integer Number of seconds since the camera boot. api String Array List of supported APIs.

endpoints Object Details about the camera’s endpoints described below. _vendorSpecific [type] (optional) Vendor specific additional info about the camera. endpoints: is a JSON object containing information about the camera’s endpoints.

Name

_Type

_Description

httpPort Integer Port for HTTP server. (Default 80) httpUpdatesPort Integer Port to receive updates over HTTP.

(9)

httpsUpdatesPort (Optional) Integer Port to receive updates over HTTPs.

Errors

No errors

Input & Output Example

Request Input

_{Output Response}

{ "manufacturer": "XXXX", "model": "XXXX", "description": "XXXX", "serialNumber": "XXXX", "firmwareVersion": "XXXX", "hardwareVersion": "XXXX", "supportUrl": "XXXX", "gps": XXXX, "gyro": XXXX, "uptime": XX, "api": [ "/osc/info", "/osc/state", "/osc/checkForUpdates", "/osc/commands/execute", "/osc/commands/status" ], "endpoints": { "httpPort": XX, "httpUpdatesPort": XX, }, }

cURL Example

curl X GET H "contenttype: application/json" http://192.168.1.168/osc/info

(10)

b. state

Description

The /osc/state API returns state of the camera. The difference between this and the info API is that the state contains mutable parameters that we’d like to be notified about the camera, (e.g. battery level), while the info only contains static attributes of the camera (e.g. manufacturer or attributes that don’t change often like firmware version).

Input

No input.

Output

Name

_Type

_Description

fingerprint String Fingerprint (unique identifier) of the current camera state. state Object State description of the camera according to the state

specification below.

state: is a JSON object containing information about the camera state.

Name

_Type

_Description

sessionId String ID of the current session. Only available if a session is start. sessionTimeout Integer Remaining time of the current session.

_cameraState String Current state of the camera e.g. "recording" "idle " "busy " "setting" or "error".

batteryLevel Number Expressed as an integer point value of the battery remaining, e.g. 75 (out of 100).

storageChanged Boolean True if a new type of storage (e.g. a SD card or a USB drive) is inserted/removed. (needed for Google OSC, always flase for us)

TotalSpace Integer Total available space in bytes on SD card remainingSpace Integer Remaining space in bytes on SD card

remainingPictures Integer Remaining pictures count available to capture for image/burst/timelapse modes

(11)

_vendorSpecific [type] (optional) Vendor specific additional state about the camera.

Errors

No errors

Example

Input Request

_{Output Response}

{ "fingerprint": "XXXXXX", "state": { "sessionId": "XXXXXX", "sessionTimeout": XX, "sessionExclusive": XXXX, "_cameraState": "XXXX", "batteryLevel": XX, "totalSpace": XX, "remainingSpace": XX, ... } }

cURL Example

curl X GET H "contenttype: application/json" http://192.168.1.168/osc/state

(12)

c. commands

Description

The commands API executes specified commands on the camera and checks the status (in progress, done etc.) of executed commands. All commands need to be implemented based on the specification in the OSC API Specification.

Note: ● After a command returns state done and results, or error state, the camera may forget about command ID.

● Response to command “camera.getImage”needs to be “ContentType: image/jpeg” when the state is done.

Execute

The /osc/commands/execute API executes specified commands on the camera. The output is a command object.

Input

Name

_Type

_Description

name String Name of the command to be executed.

parameters Object Command input parameters according to the command definitions specification.

Please refer to “OSC API Specification” for examples.

Output

Name

_Type

_Description

name String Name of the command (same as in input).

state String State of the command. Could be one of the following: ● "done" command is complete, results has been returned in this response

● "inProgress" command execution is still in progress ● "error" command has failed, see error in the response id (Optional) String Command ID. This value is required for commands returning

states inProgress. For example, the takePicture command takes a few seconds due to the need for stitching.

(13)

results (Optional) Object Command results. This value is required for commands returning state done if the command is expected to return any results, e.g. “results” : { “AAA”: “BBB”, ... }. Please refer to “OSC API Specification” for examples.

error (Optional) Object Command error description. This value is required for commands returning state error, e.g. “error”: { “code”: “badSessionId” } progress (Optional)

Object Command progress description. This value is required for commands returning state inProgress, e.g. “progress”: { “completion”: X.X }

Errors

Error Code

_Description

unknownCommand Command executed is unknown. cameraInExclusiveUse Camera is already in exclusive use, new session can’t be started. missingParameter Any required parameter is not specified. invalidParameterName Any input parameter or option name is unrecognized or supported. invalidParameterValue Any input parameter or option name is recognized, but its value is

invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect or the continuationToken is out of range or the option value is incorrect.

(14)

Input & Output Example

Input Request

_{Output Response}

_{Error Output}

{ "parameters" :{ "sessionId": "XXXXXX", "timeout" : XX } } { "results" :{ "sessionId": "XXXXXX", "timeout": XX } } { "error":{ "code": "invalidParameterName", "message": "parameter sessionId is missing" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.updateSession", "parameters": {"sessionId": "XXXXXXXXXX", "timeout": XX}}'

(15)

Error Handling

Please use the "200 OK" status code for all errors defined in this specification. For all other errors, the choice of status code (e.g. 400 or 500) is at the discretion of the manufacturer. The response should always include a JSON body in the following format for ANY error case:

{ "name": "camera.info", "state": "error", "error": { "code": "serverError", "message": "cannot get camera info." } }

“name” can be any of “camera.info”, “camera.state”, “camera.checkForUpdates”, “camera.commands.status” and “camera.commandName”.

“code” should be “serverError” for 5XX status code, “clientError” for 4XX status code and any of the three (missingParameter, invalidParameterName and invalidParameterValue) for 200 status code.

(16)

API SPECIFICATION

(17)

Overview

This document describes a proposed set of commands for a variety of oneclick spherical cameras (with builtin wifi). The goal is to allow any app on any camera (current target is Android) to control any connected spherical camera which implements this API.

Commands

Commands input/output are in JSON format and part of HTTP request/response respectively. Please refer to Open Spherical Camera API Manufacturer Guide for more complete examples.

(18)

(19)

a. camera.startSession

Description

Starts a session that times out after a fixed interval. Locks the camera to the requesting client, and makes sure the camera stay awake.

Command Parameters

Parameters

Type

Description

Possible Input

timeout (optional) int Requested session timeout in seconds. If not omitted, the server is responsible for determining a reasonable timeout. [0 ; +

∞

]

Results

Errors

 sessionId : Unique identifier to be used for this session.

 timeout :_{Responded session timeout in} seconds.

 cameraInExclusiveUse : camera is already in exclusive use, new session can’t be started.

 invalidParameterName : any input parameter is unrecognized.

 invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, e.g. it is out of range or its type is incorrect.

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "timeout" : XX } } { "results" :{ "sessionId": "XXXXX", "timeout": XX } } { "error":{ "code": "cameraInExclusiveUse", "message": "camera already in exclusive use" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.startSession", "parameters": {"timeout": XX}}'

(20)

b. camera.closeSession

Description

Disconnects from camera.

Command Parameters

Parameters

Type

Description

Possible Input

sessionId String Unique session identifier obtained from the camera.startSession command. Composed by 10 characters.

Results

Errors

This command returns no result.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

 invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXXX" } } { "error":{ "code": "invalidParameterValue", "message": "parameter sessionId is incorrect type" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.closeSession", "parameters": {"sessionId": "XXXXXXXXXX"}}'

(21)

c. camera.updateSession

Description

Refreshes the session timeout.

Command Parameters

Parameters

Type

Description

Possible Input

sessionId String Unique session identifier. Composed by 10 characters. timeout (optional) int Requested session timeout in seconds.

If it is omitted (HTTP request has no body), the server is responsible for determining a reasonable timeout. [0 ; +

∞

]

Results

Errors

 sessionId : Unique identifier to be used for this session.

 timeout :_{Responded session timeout in} seconds.

 missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXXX", "timeout" : XX } } { "results" :{ "sessionId": "XXXXXX", "timeout": XX } } { "error":{ "code": "invalidParameterName", "message": "parameter sessionId is missing" } }

(22)

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.updateSession", "parameters": {"sessionId": "XXXXXXXXXX", "timeout": XX}}'

(23)

d. camera.wifiMode

Description

Sets the wifi mode of the camera. Options are APP mode, LAN mode, or OFF. Before changing the mode, current session is closed. If the requested mode correspond to the wifi mode configured on the camera, nothing happen.

Command Parameters

Parameters

Type

Description

Possible Input

sessionId String Unique session indentifier obtained from the camera.startSession command.

Composed by 10 characters mode String Requested wifi mode “LAN”: Station mode

“direct”: Access Point mode “OFF”: wifi off

Results

Errors

This command return no result.  invalidParameterName : any input parameter is unrecognized.

 invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, e.g. it is out of range or its type is incorrect.

 invalidOperation : wifiMode command isn’t available when camera is on PoE mode

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXX", "mode": “XXXXX” } } { "error":{ "code": "invalidParameterName", "message": "parameter sessionId is missing" } }

(24)

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.wifiMode", "parameters": {"sessionId": "XXXXXXXXXX", "mode": "LAN"}}'

(25)

II. Recording & Shooting

(26)

a. camera.takePicture

Description

Captures equirectangular images when the captureMode option is specified as “image” or “_burst”, saving lat/long coordinates to EXIF (if your camera GPS is enabled).

Command Parameters

Parameters

Type

Description

Possible Input

Results

Errors

 fileUri: URL of the picture taken.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXXX" } } { "results" :{ "fileUri": "file URI" } } { "error":{ "code": "invalidParameterValue",

"message": "not available on this captureMode"

} }

cURL Example

(27)

b. camera._startRecording

Description

Starts recording video when the captureMode option is specified as “_video”. When the camera captureMode has been set to “_timelapse”, begins capturing pictures.

Command Parameters

Parameters

Type

Description

Possible Input

Results

Errors

This command returns no result.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXXX" } } { "error":{ "code": "invalidParameterValue",

"message": "sessionId type is invalid"

} }

(28)

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._startRecording", "parameters": {"sessionId": "XXXXXXXXXX"}}'

(29)

c. camera._stopRecording

Description

Ends recording video when the captureMode option is specified as “_video”. When the camera captureMode has been set to “_timelapse”, ends capturing pictures.

Command Parameters

Parameters

Type

Description

Possible Input

Results

Errors

 fileUri: URI of recorded video or the picture taken.

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXXX" } } { "results" :{ "fileUri": "file URI" } } { "error":{ "code": "invalidParameterValue", "message": "Camera is busy" } }

(30)

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._stopRecording", "parameters": {"sessionId": "XXXXXXXXXX"}}'

(31)

d. paramState

Description

This is the camera server push command. Using this technique the connection is held opened and new pieces of information can be pushed over that existing connection, from server to client, without the connection being closed and reopened as it is with “HTTP LongPolling”. The client can then refresh information whenever there is a change on the server.

Input

No input

Output

Name

Type

Description

recordStatus boolean Indicates if the camera is in recording/take picture state. timelapseRecorded

Pictures

number On timelapse mode, the camera returns the number of recorded pictures.

convStatus boolean Indicates if the camera AE/AWB convergence flag is done and then ready to record picture.

alertBatteryLevel boolean Indicates that the camera is in low battery level (level<10%) changingMode object Indicates when camera is in changing mode status. It has

two entries:

changingFlag: A boolean that becomes true when the camera is changing mode.

switchToCaptureMode: A string representing the new capture mode to which the camera changes. List of capture mode: [“_video”, “image”, “_burst”, “_timelapse”, “_setting”, “_live”] . Not available when changingFlag is false.

powerDownStatus boolean Indicates if the camera is shutting down

Errors

(32)

Example

Input Request

_{Output Response}

{ "recordStatus": false, "timelapseRecordedPictures": 0, "convStatus": false }

cURL Example

curl X GET H "contenttype: application/json" http://192.168.1.168/osc/paramState

III. Navigate & Get Information

(33)

a. camera._getAttributes

Description

Fetches attributes/metadata of the entity in the file system.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Path of a file entry to get attributes for "mnt/mmc/DCIM/360C AM01/…"

Results

Errors

 entry: file system entry object which content is: name : name of the entry object kind : file or directory isLink : is the entry object a symbolic link or not modificationTimeMs : timestamp of entry modification

time

sizeBytes : size in bytes

videoDuration : if entry is a video file, duration in

seconds

videoWidth : if entry is a video file, width in pixels videoHeight : if entry is a video file, height in pixels

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI" } } { "results": { "entry": { "name": "360_XXXX.JPG", "kind": "file", "isLink": false, "modificatioTimeMs" : XXXXXXX, "sizeBytes": XXX } } } { "error":{ "code": "invalidParameterValue", "message": "permissionDenied or badUri" } }

(34)

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._getAttributes", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG"}}'

(35)

b. camera._listDirectory

Description

Lists content of a single directory. The content are returned in the order of modification time, newest first.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Absolute path of the directory to list. "mnt/mmc/DCIM/360C AM01/…" entryCount int Desired number of entries to return. [0 ; +

∞

] continuationToken String An opaque continuation token returned

by previous "_listDirectory" command, can be used to retrieve next part of a huge directory. Composed by 10 characters.

Results

Errors

 entries: list of entries which content is : name : name of the entry object kind : file or directory isLink : is the entry object a symbolic link or not modificationTimeMs : timestamp of entry modification

time

sizeBytes : size in bytes

videoDuration : if entry is a video file, duration in

seconds videoWidth : if entry is a video file, width in pixels videoHeight : if entry is a video file, height in pixels  totalEntries: total number of entries to return.

 continuationToken : it is set only if result is complete. If the client wishes to fetch remaining entries, it should do another "_listDirectory" command with token set.

(36)

(37)

Input & Output

Command Input

Command Output

Output Error31

{ "parameters" :{ "fileUri": "file URI", "entryCount": XX, "continuationToken": "XXXXXX" } } { "results" :{ "entries": [ { "name": "360_XXXX.JPG", "kind": "file", "isLink": false, "modificatioTimeMs": XXXXXX, "sizeBytes": XXX }, { "name": "subdir", "kind": "directory", "isLink": true, "modificationTimeMs" : XXXXXX, } ] "totalEntries": XX, "continuationToken": "XXXXXX" } } { "error":{ "code": "invalidParameterName", "message": "entryCount parameter is unrecognized" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._listDirectory", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01", "entryCount": XX }}'

(38)

c. camera._getStreamUrl

Description

Gets network streaming (rtsp) URL from camera. This stream can be the main or preview stream if supported.

Command Parameters

Parameters

Type

Description

Possible Input

sessionId String Unique session identifier obtained from the camera.startSession command.

Composed by 10 characters. type String Stream type. "main" or "preview" protocol String Stream protocol "rtsp" or "rtmp" userName String User ID for live stream authentication "360camxxx" password String User password for live stream

authentication

"giroptic"

Note: “userName” and “password” options are needed (if defined) on PoE or BulB extension mode. They must be defined with the command: camera.setLiveStreamAuthentication For more information, refer to this doc: https://docs.google.com/document/d/1ws9hNFCmY9AO59pByQnyFbUevyrl4TrZ9HGgBGElAk/edit

Results

Errors

 url: network stream URL.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

(39)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "sessionId": "XXXXXX", "type": "stream type", "protocol": "stream protocol" } } { "results" :{ "url": "stream URL" } } { "error":{ "code": "invalidParameterName", "message": "input parameter is unrecognized" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._getStreamUrl", "parameters": {"sessionId": "XXXXXXXXXX", "type": "XXXX", "protocol": "XXXX"}}'

(40)

IV. Read, Edit & Delete

(41)

a. camera._readFile

Description

Reads content of a file, by default it reads the whole content, but user might choose to read only a particular range.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Path of the file to read. "mnt/mmc/DCIM/360C AM01/…" range (Optional) Object Range of the file to read, if not

provided content of the whole file is returned. Contains 2 parameters : ● firstByte : number ● lastByte : number “range”: { “firstByte”: XX, “lastByte”: XX }

format (Optional) String Content format of the file returned, base64 or blob, if not provided, the content of the file is "base64" encoded.

"base64" or "blob"

Results

Errors

 content : content of the file returned as base64 encoded string or blob binary data depending on the format parameter. If blob format is chosen, http body’s content is just requested binary data.

(42)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI", "range": { "firstByte": XX, "lastByte": XX }, "format": "XXXX" } } { "results" :{ "content": "format content" } } { "error":{ "code": "invalidParameterValue",

"message": "range input parameters are incorrect type" }

}

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._readFile", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG"}}'

(43)

b. camera._writeFile (unactive)

Description

Writes content into a file, it also can create the file if it doesn’t exist yet.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Absolute path of the file to be written. "mnt/mmc/DCIM/360C AM01/…" writeMode String Write can have the following value:

● "append": the given content is appended the end of the file ● "overwrite": given content

replace the current content of the file

"append" or "overwrite"

mustNotExist (optional)

Boolean Used to guarantee that existing file is not overridden by this operation. If set to true, the command will fail in case of conflict, if unset or set to false an existing file will be silently overridden.

'true' or 'false'

content String Content to be written in Base64 format.

Note: The request “ContentLength” (from request header)must not exceed 1500 Kbytes size.

Results

Errors

Command doesn’t have any result.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

(44)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "/mnt/mmc/file.txt", "content": "AABBCC", "writeMode": "overwrite", "mustNotExist": false } } { "error":{ "code": "invalidParameterValue",

"message": "internal server error"

} }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._writeFile", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG", "writeMode": "overwrite", "content": "AABBCCDDEEaabbccdd1234"}}'

(45)

c. camera.delete

Description

Deletes a single file or directory.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Path of the file or directory to be deleted.

"mnt/mmc/DCIM/360C AM01/…" recursive Boolean Whether to delete recursively, only

applied for directory deletion. Command fails when this parameter is set to false, but the directory is not empty.

'true' or 'false'

Results

Errors

Command doesn’t have any result.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

 invalidParameterValue : any input parameter is recognized, but its value is invalid for various reasons, for example, the sessionId doesn't exist or it is not active any more or its type is incorrect.  unauthorizedCommand

(46)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI" } } { "error":{ "code": "invalidParameterValue",

"message": "need recursive flag for directory"

} }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.delete", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG", "recursive": XXXX }}'

(47)

V. Metadata Commands

(48)

a. camera.getMetadata

Description

Gets metadata of a file given its URI. The fields of Exif and XMP are listed in Image header.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String URI of the file to get metadata for. It is up to manufacturers to decide whether to use absolute or relative URIs. Clients may treat this as an opaque identifier. "mnt/mmc/DCIM/360C AM01/…"

Results

Errors

 exif : JSON object containing JPEG exif metadata (including GPS information). Does not include image or thumbnail.

 xmp : JSON object containing Photosphere XMP.

(49)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI" } } { "results": { "exif": { "ImageWidth": XX, "ImageLength": XX, ……. }, "xmp": { "ProjectionType": "XXXX", "UsePanoramaViewer": XXXX, …… } } } { "error":{ "code": "invalidParameterName", "message": "parameter fileUri is missing" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.getMetadata", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG " }}'

(50)

b. camera._setMetadata

Description

When setting image metadata, the JSON dictionary must be complete, and any tags missing are considered deletions and should be handled, with a missing mandatory tag causing the command request to return failure. A client should fetch the current metadata and modify it appropriately before setting it.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Path to or ID of the file to set metadata. "mnt/mmc/DCIM/360C AM01/…" exif Object TIFF, Exif, and GPS tag information in

JSON format.

Results

Errors

Command has no return value.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

(51)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI", "exif": { "ImageWidth": XX, "ImageHeight": XX, "GPSLatitude": XX, "GPSLongitude": XX } } } { "error":{ "code": "invalidParameterName", "message": "parameter exif is unrecognized" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._setMetadata", "parameters": {"fileUri": /mnt/mmc/DCIM/360CAM01/360_XXXX.JPG ", "exif": {"GPSLatitude": XX, "GPSLongitude": XX} }}'

(52)

c. camera._patchMetadata

Description

When patching image metadata, the JSON dictionary is a delta to apply over the current image metadata, with the tag present adding to or replacing metadata information in the file. This provides a camera client with an easy way of adding or changing the Rating or RatingPercent tags, without having to first fetch the current image metadata.

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String Path to or ID of the file to patch metadata.

"mnt/mmc/DCIM/360C AM01/…" exif Object TIFF, Exif, and GPS tag information in

JSON format.

Results

Errors

Command has no return value.  missingParameter : any required parameter is not specified, e.g. sessionId is not specified.

(53)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI", "exif": { "GPSLatitude": XX, "GPSLongitude": XX } } } { "error":{ "code": "invalidParameterName", "message": "parameter exif is unrecognized" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera._patchMetadata", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG", "exif": {"GPSAltitude": XX}}}'

(54)

VI. Image Commands

(55)

a. camera.getImage

Description

Returns a full size or scaled image given its path. Input parameters include resolution. This command should return "ContentType: image/jpeg".

Command Parameters

Parameters

Type

Description

Possible Input

fileUri String URI of the target file. Manufacturers decide whether to use absolute or relative URIs. Clients may treat this as an opaque identifier.

"mnt/mmc/DCIM/360C AM01/…"

maxSize (optional) Number Maximum size of the requested image, max (scaledimage_width, scaledimage_height).

If missing, a full size image is returned. If maxSize is larger than full size, a fullsize image is returned too. [0 ; +

∞

]

Results

Errors

content: image binary data, including corresponding (e.g. scaled) metadata in image header.

(56)

Input & Output

Command Input

Command Output

Output Error

{ "parameters" :{ "fileUri": "file URI", "maxSize": XX } } { "error":{ "code": "invalidParameterValue", "message": "invalid maxSize parameter" } }

cURL Example

curl X POST H "contenttype: application/json" http://192.168.1.168/osc/commands/execute d '{"name": "camera.getImage", "parameters": {"fileUri": "/mnt/mmc/DCIM/360CAM01/360_XXXX.JPG", "maxSize": XX }}'

Open Spherical Camera API Version 1.1.2