Getting Started

Unlike the RICOH THETA and RICOH THETA m15, communication for the RICOH THETA S or above are performed via HTTP connection.

This section explains the flow from capturing a still image to acquiring the file.

  1. Set API version
  2. Acquire status prior to shooting
  3. Acquire/Set properties
  4. Shoot still image
  5. Confirm file save
  6. Acquire file

1. Set API version

Camera API version should be set to v2.1 with clientVersion in order to use RICOH THETA API v2.1, because the API version at the start point of the connection via wireless LAN is v2.0.

Since a session should be started before executing commands in API v2.0, camera.startSession for session start and camera.setOptions for setting properties are used.

Request (start session)

POST /osc/commands/execute
{
    "name": "camera.startSession",
    "parameters": {}
}

Response

{
    "name": "camera.startSession",
    "state": "done",
    "results": {
        "sessionId": "SID_0001",
        "timeout": 180
    }
}

Request (setting camera API version)

POST /osc/commands/execute
{
    "name": "camera.setOptions",
    "parameters": {
        "sessionId": "SID_0001",
        "options": {
            "clientVersion": 2
        }
    }
}

Response

{
    "name": "camera.setOptions",
    "state": "done"
}

2. Acquire status prior to shooting

The status of the device is acquired as pre-preparation to confirm whether the file save process is complete.

Check the status ID (fingerprint) and newest file URL (state._latestFileUrl) with State.

Request

POST /osc/state

Response

{
    "fingerprint": "FIG_0003",
    "state": {
        "batteryLevel": 1.0,
        "storageUri": "http://192.168.1.1/files/abcde/",
        "_captureStatus": "idle",
        "_recordedTime": 0,
        "_recordableTime": 0,
        "_latestFileUrl": "http://192.168.1.1/files/abcde/100RICOH/R0010004.MP4",
        "_batteryState": "disconnect",
        "_apiVersion": 2
    }
}

3. Acquire/Set properties

In order to aquire specified properties, camera.getOptions is used.

This is an example of acquisition the image format property (fileFormat) and its support value.

Request

POST /osc/commands/execute
{
    "name": "camera.getOptions",
    "parameters": {
        "optionNames": [
            "fileFormat",
            "fileFormatSupport"
        ]
    }
}

Response

{
    "name": "camera.getOptions",
    "state": "done",
    "results": {
        "options": {
            "fileFormat": {
                "type": "jpeg",
                "width": 5376,
                "height": 2688
            },
            "fileFormatSupport": [
                { "type": "jpeg", "width": 5376, "height": 2688 },
                { "type": "jpeg", "width": 2048, "height": 1024 }
            ]
        }
    }
}

In order to set specified properties, camera.setOptions is used.

This is an example of setting the image format property (fileFormat) for setting the still image size to 2048x1024.

Request

POST /osc/commands/execute
{
    "name": "camera.setOptions",
    "parameters": {
        "options": {
            "fileFormat": {
                "type": "jpeg",
                "width": 2048,
                "height": 1024
            }
        }
    }
}

Response

{
    "name": "camera.setOptions",
    "state": "done"
}

4. Shoot still image

Operates the shutter. The shutter operation command differs depending on whether it is still image shooting (single shooting), continuous shooting.

camera.takePicture is used for still image shooting, and camera._startCapture and camera._stopCapture are used for continuous shooting.

Request

POST /osc/commands/execute
{
    "name": "camera.takePicture"
}

Response

The state returns to "inProgress" immediately after the shutter is operated in case of still image shooting.

{
    "name": "camera.takePicture",
    "state": "inProgress",
    "id": "1",
    "progress": {
        "completion": 0.00
    }
}

5. Confirm file save

Check changes to the device status in CheckForUpdates, and detect whether file save is completed in State.

Request

Changes to the device status can be checked by changes to the status ID (stateFingerprint) of CheckForUpdates.

POST /osc/checkForUpdates
{
    "stateFingerprint": "FIG_0003"
}

Response

{
    "stateFingerprint": "FIG_0004"
}

Request

When a file is saved, the file URL saved in state._latestFileUrl of State is entered. If a status change other than file save occurs or the state does not change due to a CheckForUpdates timeout, it is necessary to repeatedly call and wait until the file is saved.

POST /osc/state

Response

{
    "fingerprint": "FIG_0006",
    "state": {
        "batteryLevel": 0.67,
        "storageUri": "http://192.168.1.1/files/abcde/",
        "_captureStatus": "idle",
        "_recordedTime": 0,
        "_recordableTime": 0,
        "_latestFileUrl": "http://192.168.1.1/files/abcde/100RICOH/R0010005.JPG",
        "_batteryState": "disconnect",
        "_apiVersion": 2
    }
}

6. Acquire file

Acquire the file using file URL and GET request.

When performing the acquired still image top/bottom correction, use the XMP (GPano:PosePitchDegrees / GPano:PoseRollDegrees) contained in the image data. See Photo Sphere XMP Metadata for details on XMP.

Request

GET /files/abcde/100RICOH/R0010005.JPG

Response

(Binary data)

Page top