Using BASH Scripts To Easily Test THETAs

jcasman · February 11, 2021, 12:39am

Needing to put your THETA through some repetitive API testing and curl isn’t flexible enough? Wouldn’t it be nice if there was a simple scripting tool to test a series of commands? Use it to isolate problems, set and quickly see different values easily, and lots more.

theta360.guide has building BASH scripts to automate testing. You can easily run a sequence of API commands just from your development machine, connected to a THETA, and get a great feel of how your THETA performs.

I’m working on a Windows 10 machine. For now, you need to have WSL2 installed. I’m running Ubuntu 20.04.

Go to:
SC2 Developers - Community Docs, Code Samples and Tutorial Videos

The registration and the command line tool are free. Binaries are available for Linux, Windows, Mac and Raspberry Pi. Or you can compile the code yourself!

Connect your development machine to your THETA over Wi-Fi.

There are two scripts currently. I expect this number to increase. If you want to take a look at the scripts, you can look here: webapi/script_examples at master · theta360developers/webapi · GitHub

I am using bash_sample2.sh

bash_sample2 performs the following commands

It does getOptions

Then it sets exposureCompensation to -2.0

It downloads the picture

Then it sets exposureCompensation to -1.0

It downloads the picture

Then it sets exposureCompensation to 0.0

It downloads the picture

Then it sets exposureCompensation to 1.0

It downloads the picture

Then it sets exposureCompensation to 2.0

It downloads the picture

Here’s the output of testing it with a Z1 running firmware 1.60.1

Viewed in Windows Explorer:

The 5 images:

Command line output

jcasman@DESKTOP-MFMN3HS:/mnt/c/Users/jcasm/Development/webapi/script_examples$ ./bash_sample2.sh

{
  "name": "camera.getOptions",
  "results": {
    "options": {
      "_autoBracket": {
        "_bracketNumber": 2,
        "_bracketParameters": [
          {
            "aperture": 2.1,
            "_colorTemperature": 5000,
            "exposureCompensation": 0.0,
            "exposureProgram": 1,
            "iso": 400,
            "shutterSpeed": 0.004,
            "whiteBalance": "auto"
          },
          {
            "aperture": 2.1,
            "_colorTemperature": 5000,
            "exposureCompensation": 0.0,
            "exposureProgram": 1,
            "iso": 400,
            "shutterSpeed": 0.004,
            "whiteBalance": "auto"
          }
        ]
      },
      "captureMode": "image",
      "_colorTemperature": 5000,
      "dateTimeZone": "2021:02:10 09:49:31-08:00",
      "exposureCompensation": 0.0,
      "exposureDelay": 0,
      "exposureProgram": 2,
      "_filter": "off",
      "offDelay": 64800,
      "previewFormat": {
        "framerate": 30,
        "height": 512,
        "width": 1024
      },
      "remainingSpace": 20551598080,
      "shutterSpeed": 0,
      "_shutterVolume": 100,
      "sleepDelay": 65535
    }
  },
  "state": "done"
}
The EV is now -2.0. Did it work?  If so, take a moment to celebrate.
Test of taking picture and then checking to see if picture is ready for download
---
The status ID is 24
Elapsed time: 0 seconds. State: inProgress
Elapsed time: 1 seconds. State: inProgress
Elapsed time: 2 seconds. State: inProgress
Elapsed time: 3 seconds. State: done
picture ready for download at http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010093.JPG
Writing file from the following URL
http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010093.JPG
download complete
The EV is now -1.0. Did it work?  If so, take a moment to celebrate.
Test of taking picture and then checking to see if picture is ready for download
---
The status ID is 25
Elapsed time: 0 seconds. State: inProgress
Elapsed time: 1 seconds. State: inProgress
Elapsed time: 2 seconds. State: inProgress
Elapsed time: 3 seconds. State: done
picture ready for download at http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010094.JPG
Writing file from the following URL
http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010094.JPG
download complete
The EV is now 0.0. Did it work?  If so, take a moment to celebrate.
Test of taking picture and then checking to see if picture is ready for download
---
The status ID is 26
Elapsed time: 0 seconds. State: inProgress
Elapsed time: 1 seconds. State: inProgress
Elapsed time: 2 seconds. State: inProgress
Elapsed time: 3 seconds. State: done
picture ready for download at http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010095.JPG
Writing file from the following URL
http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010095.JPG
download complete
The EV is now 1.0. Did it work?  If so, take a moment to celebrate.
Test of taking picture and then checking to see if picture is ready for download
---
The status ID is 27
Elapsed time: 0 seconds. State: inProgress
Elapsed time: 1 seconds. State: inProgress
Elapsed time: 2 seconds. State: inProgress
Elapsed time: 3 seconds. State: done
picture ready for download at http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010096.JPG
Writing file from the following URL
http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010096.JPG
download complete
The EV is now 2.0. Did it work?  If so, take a moment to celebrate.
Test of taking picture and then checking to see if picture is ready for download
---
The status ID is 28
Elapsed time: 0 seconds. State: inProgress
Elapsed time: 1 seconds. State: inProgress
Elapsed time: 2 seconds. State: inProgress
Elapsed time: 3 seconds. State: done
picture ready for download at http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010097.JPG
Writing file from the following URL
http://192.168.1.1/files/90014a68423861503e0302775cb7b500/100RICOH/R0010097.JPG
download complete

It’s a useful tool and there’s a lot more I - or you! - can do with it. I’ll be working with it more and posting more results.

For example, there are clearly differences between Z1 and SC2. I will be doing more testing to compare models and find out strengths and weaknesses of both.

If you use the script and have comments or suggestions, please let me know. If you’d like a Linux version of the executable, drop a line, we can make one.

craig · February 11, 2021, 2:23pm

@jcasman, thanks for posting your test. I’ve been using this technique of bash scripts with the command line theta.exe tool and am enjoying the process. I’ve used the following in the past:

bash with curl (likely the most common way)
Postman and Restlet Client with saved scripts
Python with custom Python module
Node test framework

Even though the theta.exe tool is incomplete, the process is nice because theta.exe has a help menu and some level of checking for correct values. We can expand the help menus and error checking in the future. It looks like a promising project.

Please continue to test this technique, possibly with the bracketed Z1 shots described in this post by Pixel. Consider testing it in two ways:

setting shutter speed and parameter per shot and then use takePicture. This is the process that Pixel is using in his post
setting _autoBracket and then use startCapture

I’ve updated the tool so that you can pass it any option on the command line. For complex options like _autoBracket, you can save the option to a file and then read it in.

I’ve added a README to the script_examples folder.

bash scripts for RICOH THETA WebAPI

You can use bash scripts to run the command line tester from Oppkey on the RICOH THETA cameras.
The tester is incomplete. We use it for our own testing and make it available so
people can replicate our tests or run their own tests. Good alternatives to this
tool are curl and Postman. As this
tool is incomplete, it can’t replace curl or Postman. However, it can help you
to browse the THETA API functionality and test behavior without having to constantly reference
the API documentation.

To see available commands run ./theta.exe --help

PS C:\Users\craig\Documents\Development\ricoh\webapi> .\theta.exe --help
RICOH WebAPI Tester

Usage: ./theta <command> [arguments]       

Global options:
-h, --help    Print this usage information.

Available commands:
  autoBracket            apply test 3 image auto bracket settings
  deleteAll              DANGER: Delete all image and video files from camera
  downloadFile           Download newest file and save to local computer
  exposureCompensation   set exposure compensation with --value=2.0
  exposureDelay          set self timer delay in seconds
  exposureProgram        set exposure program 1 (manual), 2 (auto), 3 (aperture Z1 only), 4 (shutter), 9 (iso)        
  getMetadata            Get image metadata from camera by passing URL of the file
  getOptions             get camera options
  getTimeShift           get Time Shift settings. SC2B, V, Z1 only
  hdr                    Enable, save, delete, disable, and show hdr settings
  info                   Camera info: model, serialNumber, apiLevel...
  listFiles              list all image and video files on camera
  listUrls               print and return URLs as an array of strings
  offDisable             Disable power off
  preset                 SC2 only. Preset shooting modes. face, night, lens-by-lens
  reset                  Reset camera settings. Camera will turn off. Need to reconnect
  resetMySetting         Reset mySettings (saved settings) to factory default
  setLanguage            Z1, V only. Set language with --lang=en-US
  setModeImage           Set camera to image mode
  setShutter             set shutter speed
  sleepDisable           Disable camera auto-sleep.
  startCapture           Start capture. Must specifiy capture mode
  state                  Camera state: batteryLevel, storageUri...
  status                 Show camera status. Requires id value returned from takePicture
  takeAndDownload        Take picture. Show elapsed time. Download to local disk.
  takeAndReady           Take picture. Show elapsed time. Show file URI when ready for download
  takePicture            take picture, similar to pressing shutter button
  thumbGet               Print image thumbnail byte data to screen. Pass URL of the file
  thumbWriteAll          Download and save all thumbnails to local storage.

Run "./theta help <command>" for more information about a command.

setting complex options

Most of the commands and options are specified on the same line as theta.exe.

For most options, you do not need to create an options file. If the value
of the option is a single word or number, specify the value with this convention.

.\theta.exe setOption --name=captureMode --value=video

If the option consists of multiple parts, you can store the option parameters
in a file as a JSON string. You can then use the file with the command below.

theta.exe setOption --jsonFile=options/bracket_2_config.json

You can see the parameters with ./theta.exe getOptions

> .\theta.exe getOptions
200
{
  "name": "camera.getOptions",
  "results": {
    "options": {
      "_autoBracket": {
        "_bracketNumber": 2,
        "_bracketParameters": [
          {
            "aperture": 2.1,
            ...

format of options file

The options file contains a JSON string. It is not a dart map, though the
formats look almost identical.

single option example of complex _autobracket

cat options/bracket_2_config.json
{
    "_autoBracket": {
      "_bracketNumber": 2,
      "_bracketParameters": [
        {
          "shutterSpeed": 0.004,
          "iso": 400,
          "_colorTemperature": 5100,
          "exposureProgram": 1,
          "whiteBalance": "auto"
        },
        {
          "shutterSpeed": 0.004,
          "iso": 320,
          "_colorTemperature": 5100,
          "exposureProgram": 1,
          "whiteBalance": "auto"
        }
      ]
    }
  }