SDK - Camera Operation details

From edgertronic high speed video camera
Jump to: navigation, search


Home

Camera File Systems




Boot sequence

The camera boots using the DM368 ROM Bootloader (RBL), which loads the User Bootloader (UBL) from the micro SD card. UBL load U-boot, and U-boot's environment, checks if you were holding the multi-purpose and/or trigger button(s) down, and then boots Linux. At the end of Linux boot process, the init script executes the entries in /etc/rc.d, which handle device update, networking, and of course starting the main python high speed camera application.

If U-boot detects the multi-purpose was held down during power-on, a factory reset is performed.

If U-boot detects both external trigger buttons and the multi-purpose were held down during power-on, the serial console is enabled and the u-boot automatic boot is interrupted and the camera has the serial console active waiting for the user to enter a u-boot command.

The lighttpd configuration file uses /home/root/ss-web/app.fcgi as the default home page. The fast CGI script starts the app.py which supports the dynamic interaction between the JavaScript running on the web browser and the rest of the software on the camera. app.py uses CAMAPI and can be reviewed as an example python application for those considering writing their own software that uses CAMAPI. The easiest way to think about app.py is an application that exposes the python CAMAPI over HTTP.

Simplified camera control flow

After booting the camera, the camera is providing live preview JPEG images, filling the pretrigger buffer, and ready to process a trigger event. The starting set of capture parameter values that are used by the camera are the last set of values the user specified. Once connected, the typical workflow interaction is shown below.


External world
(Web browser)
(User developed application)
Camera
What's going on?
(get_status)
Waiting for trigger. The pretrigger buffer is 100% full and the oldest video frame is being overwritten with the newest video frame in a circular buffer fashion.
I want you to take a big video quickly for 10 seconds)
(suggested camera configuration settings)
Ok, if I do that you can set the frame rate to 494
(camera configuration settings that will be used)
Hmm, that's not what I wanted, try these values
(suggested camera configuration settings)
Ok, if I do that you can set the frame rate to 1000
(camera configuration settings that will be used)
Are you busy?
(get_status)
I am filling the pretrigger buffer and it is 32% full
(state=CAMAPI_STATE_RUN
level=32)
Now what are you doing?
(get_status)
I am still filling the pretrigger buffer and it is 85% full
(state=CAMAPI_STATE_RUN
level=85)
Now what are you doing?
(get_status)
I have filled the pretrigger buffer, I am overwriting the oldest frame in the pretrigger buffer as new frames are received, and am waiting for a trigger event
(state=CAMAPI_STATE_RUN
level=100)
Capture video
(trigger)
Filling posttrigger buffer
(OK)
Now what are you doing?
(get_status)
I am filling the posttrigger buffer and it is 43% full
(state=CAMAPI_STATE_TRIGGERED
level=43)
Now what are you doing?
(get_status)
I am saving the video to a file and am 16% done
(state=CAMAPI_STATE_SAVING
level=16)
Now what are you doing?
(get_status)
I am filling the pretrigger buffer and it is 8% full
(state=CAMAPI_STATE_RUN
level=8)
External trigger
Now what are you doing?
(get_status)
I am filling the posttrigger buffer and it is 24% full
(state=CAMAPI_STATE_TRIGGERED
level=24)

Model View Controller

The camera software is designed to support multiple simultaneous displays, different entities controlling the camera at the same time, and all the while the same model making sure all the details of the camera are attended to. For example, you can use a laptop to configure the camera and capture a video. Then you can use the remote trigger to take capture additional videos. You can even interleave triggering from the remote trigger, the multi-function button, and from the Web UI. If you are ambitious, you can write an Android app so that you can view and trigger from any Android device. So, who is in control? Anyone and everyone. Who can view what is going on? Anyone and everyone. Who exposes the camera model that allows multiple controllers and multiple viewers? Just CAMAPI.

To support multiple controllers and multiple displays, each entity external to the camera (or for that matter, a custom application running on the camera) needs to have an interface to tell the camera what to do and an ability to read the current device status. All external entities need to check the status before changing the camera state (since another external entity may have changed it) and to expect your request to fail (for example, if an external entity changed the device state after you requested status, but did so before you issued the request to change device state).

The camera software model is exposed by CAMAPI. In addition, app.py supports a series of web URLs that expose CAMAPI via HTTP.

Trigger sources

There are four sources that can trigger the camera.

  • CAMAPI trigger() method, which is used by the Web UI.
  • Multi-purpose button
  • External trigger jack
  • Genlock daisychain cable when camera is configured as a genlock slave

A camera can triggered only if there is usable storage installed and if the camera is not calibrating or saving.

Unattended operation

When video is captured, the last allowed camera configuration settings are saved. When the camera is turned on, the saved values areread once, and those camera configuration settings are preloaded and used as the power-on camera settings. If the multi-function button or remote trigger is pressed (or any other trigger event occurs), then the video that is captured uses the power-on camera settings. This allows you to configure the camera, power down, setup the camera up in the wild, and capture videos (hope you are a good aim!).

What-if style capture parameter negotiation

There is a dependency between capture parameters, so you can specify some parameters and the camera returns the maximum value available for the other parameters. You can play "what if", by providing your desired set of parameters (where some can be unspecified) and the camera will provide the actual set that will be used. You can request various parameters and get back a consistent set of numbers multiple times until the returned set of camera parameters actually being used is acceptable.

The negotiation uses a priority scheme to resolve setting conflicts, based on a priority order is as follows:

  • iso - not dependent on other arguments.
  • exposure - not dependent on other arguments.
  • subsample - not dependent on other arguments.
  • pretrigger - not dependent on other arguments.
  • overclock - not dependent on other arguments.
  • genlock - not dependent on other arguments.
  • frame_rate - always dependent on exposure, conditionally dependent on horizontal, vertical if specified, and overclock, if specified. The genlock setting has a special effect if the device is configured as genlock slave.
  • horizontal, vertical - conditionally dependent on frame_rate if specified and overclock, if specified.
  • duration - always dependent on frame_rate, horizontal and vertical.

If the exposure value is such that the requested frame_rate can't be met, then a lower frame_rate will be used, which may allow a larger horizontal and vertical size to be valid. If the requested frame_rate is valid for the requested exposure, then the horizontal and vertical size may be reduced to meet the requested frame_rate.

If the camera is specified as genlock slave, and is connected to a genlock master which is outputting compatible timing, then the genlock slave will capture frames with the same rate and phase as the genlock master.

If the camera is specified as genlock slave, and is not connected to a genlock master, then the genlock slave will capture frames at the frame rate specified in the slave's menu settings.

If a parameter is not specified, or if a parameter is in conflict with a higher priority parameter, then the largest possible value for the lower priority parameter, consistent with the other values, is used.

You supply the requested values by passing in a dictionary of values (whose key name begins with requested_, like requested_exposure) to the configure_camera() CAMAPI. The function returns a dictionary containing both the requested values and the actual values used, along with some additional key/value pairs that need to be passed back into the CAMAPIrun() method.

To ensure your application continues to work as expected as new features are added, you should first call get_current_settings(), then override the set or requested_* values you are settings, then pass that dictionary to configure_camera(). For example, in version 2.1, requested_multishot_count was added with a default value of 1. If your version 2.0 application first calls get_current_settings(), then the returned dictionary will have that default value present. When you pass the dictionary, with your modified requested settings, back to the camera via configure_camera(), the camera will take one video and save that video as expected - just like in version 2.0. However, if you simply created a new dictionary based on the version 2.0 feature set, leaving out requested_multishot_count (since it didn't exist in version 2.0), then when you try running your application in version 2.1 the allowed multishot_count might be bigger than 1, thus changing the camera's behavior.

Camera configuration

The edgertronic camera supports two ways of being configured.

Video capture configuration is supported by CAMAPI configure_camera() and run() APIs. Specifically, the run() API updates the default video capture settings the camera uses the next time the camera is powered on. You can also save video settings via the CAMAPI favorites API save_settings().

Command line example of using curl to run the camera with specific settings:

curl -m 5 -X POST -H "Content-Type: application/json" -d \
'{"requested_duration":1.23,
"requested_edr":0,
"requested_exposure":0.00091,
"requeted_filename_pattern":"&D",
"requested_force_monochrome":1,
"requested_frame_rate":1000,
"requested_gamma_correction":1,
"requested_genlock":3,
"requested_horizontal":800,
"requested_iso":3200,
"requested_multishot_count":null,
"requested_notes":"Infield Camera",
"requested_overclock":null,
"requested_overlay_frame_number":1,
"requested_overlay_logo":0,
"requested_overlay_notes":0,
"requested_overlay_settings":0,
"requested_pipeline":"H264HIGH:pipelines_factory.txt:30/1",
"requested_pretrigger":50,
"requested_save_mode":2,
"requested_save_view":0,
"requested_subsample":0,
"requested_trigger_debounce":1,
"requested_vertical":600}' \
http://10.11.12.13/run


Camera configuration that typically is set once and then doesn't change is done by storing a configuration file on the removable storage device and then powering on the camera. You can configure ntp, network settings, video encode settings, and other camera features using Configuration Files.




Home

Camera File Systems