THETA Web API Client

Client implementation of RICOH THETA API v2.1.

Supported environments are Java, JVM languages, Android, and THETA Plug-in.

Tested on RICOH THETA V and THETA Z1. Some features for THETA S and SC are not tested.

Getting Started

Modify your build.gradle to include this library.

repositories {
    ...
    mavenCentral() // insert this line
}

dependencies {
    ...
    implementation 'org.theta4j:theta-web-api:1.6.0' // insert this line
}

Example Projects

• Android App Example
• THETA Plug-in Example

Usage for Android and THETA Plug-in

This library takes network access, so your application needs android.permission.INTERNET permission.

Insert the following line into your AndroidManifest.xml.

<uses-permission android:name="android.permission.INTERNET"/>

Network access on UI thread causes an error on Android system. You need to call API on other thread.

For more details, see the official document.

// Invalid example written in Kotlin
class MyActivity : Activity() {
    override fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
        // UI event is invoked on UI thread!!
        theta.takePicture() // this line causes error!!
        ...
    }
}

// Valid example written in Kotlin
class MyActivity : Activity() {
    private val executor = Executors.newSingleThreadExecutor()
    override fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
        executor.submit {
            // The executor's thread is not an UI thread.
            theta.takePicture() // this is OK.
        }
        ...
    }
}

Example

These examples are written in Java.

Create Theta instance

org.theta4j.webapi.Theta is central object of this library.

When use from external device and THETA is Wi-Fi access point mode.

final Theta theta = Theta.create(); // endpoint is set to http://192.168.1.1

When use from external device and THETA is Wi-Fi client mode. Digest Authentication is required in this mode.

final String endpoint = "http://192.168.100.42"; // just an example
final String username = "THETAYL00000000";       // just an example
final String password = "p@55w0rd";              // just an example
final Theta theta = Theta.create(endpoint, username, password); // specify username and password

When use from THETA Plug-in.

final Theta theta = Theta.createForPlugin(); // endpoint is set to http://127.0.0.1:8080

Take a picture

theta.takePicture();

Take a picture and wait for done

import org.theta4j.osc.CommandResponse;
import org.theta4j.osc.CommandState;
import org.theta4j.webapi.TakePicture;
...
CommandResponse<TakePicture.Result> response = theta.takePicture();
while(response.getState() != CommandState.DONE) {
    response = theta.commandStatus(response);
    Thread.sleep(100);
}
System.out.println("fileUrl: " + response.getResults().getFileUrl());

Get option value

import static org.theta4j.webapi.Options.*;
...
final ISOSpeed iso = theta.getOption(ISO);
System.out.println("ISO: " + iso);

Get multiple option values in one HTTP request

import org.theta4j.osc.OptionSet;
import static org.theta4j.webapi.Options.*;
...
final OptionSet optionSet = theta.getOptions(ISO, ISO_SUPPORT, SHUTTER_SPEED);
System.out.println("ISO: " + optionSet.get(ISO));
System.out.println("ISO Support: " + optionSet.get(ISO_SUPPORT));
System.out.println("Shutter Speed: " + optionSet.get(SHUTTER_SPEED));

Set option value

import static org.theta4j.webapi.Options.*;
import org.theta4j.webapi.ISOSpeed;
...
theta.setOption(ISO, ISOSpeed._200);

Set multiple option values in one HTTP request

import org.theta4j.osc.OptionSet;
import static org.theta4j.webapi.Options.*;
import org.theta4j.webapi.ExposureProgram;
import org.theta4j.webapi.ISOSpeed;
...
final OptionSet optionSet = new OptionSet.Builder()
        .set(EXPOSURE_PROGRAM, ExposureProgram.ISO_SPEED)
        .set(ISO, ISOSpeed._200)
        .build();          
theta.setOptions(optionSet);

Development

• Testing
• Publishing