Camera Controls

Video Capture Format

Spiri's built-in cameras are global shutter CMOS sensors and are synchronized by wire. The left camera is the leading (master) device, the right camera is the following (slave) device.

Width/Height
Pixel Format
Field
Bytes per Line
Size Image
Colorspace
1280/720
RG12
None
2560
1843200
sRGB

Driver Level Control

The camera driver on Spiri is accessed using v4l2, which provides low level control of the sensor. An example of a driver level command is:

v4l2-ctl -d /dev/video0 -c coarse_time=100

This tells the left camera (video0) to set its coarse time (roughly, its exposure) to 100 (out of 672). You can get a full menu of what v4l2-ctl can do by typing:

v4l2-ctl -h

You can only use this command after the cameras have started. In normal use, this is not how you should control the cameras, because processes further upstream will also be in play. For programming and diagnostic purposes, it remains available. Following are the controls that v4l2-ctl offers.

horizontal_flip
vertical_flip
gain_red
gain_green_r
gain_green_b
gain_blue
gain_column

auto_exposure
frame_length
coarse_time
hdr_enable
gain
bypass_mode
override_enable
height_align
size_align
write_isp_format
min=0 max=1 step=1 default=0 value=0
min=0 max=1 step=1 default=0 value=0
min=4 max=6476 step=1 default=100 value=100
min=4 max=6476 step=1 default=100 value=100
min=4 max=6476 step=1 default=100 value=100
min=4 max=6476 step=1 default=100 value=100
min=0 max=3 step=1 default=0 value=0

min=1 max=2 step=1 default=1 value=1
min=39 max=757 step=1 default=757 value=757
min=1 max=672 step=1 default=450 value=670
min=0 max=1 step=1 default=0 value=0
min=4 max=6476 step=1 default=100 value=500
min=0 max=1 default=0 value=1
min=0 max=1 default=0 value=1
min=1 max=16 step=1 default=1 value=1
min=0 max=2 default=0 value=0
min=1 max=1 step=1 default=1 value=1

Anatomy of a Camera Command

The camera launch files on a Spiri device use gstreamer and the pipeline is constructed approximately as follows.

gst-launch-1.0 -e nvcamerasrc sensor-id=0 ! \
 'video/x-raw(memory:NVMM), width=(int)1280, height=(int)720, format=(string)I420, framerate=(fraction)50/1' ! \
 nvvidconv flip-method=2 ! \
 'video/x-raw(memory:NVMM), format=(string)I420' ! omxh264enc bitrate=8000000 ! \
 'video/x-h264, stream-format=(string)byte-stream' ! \
 filesink location=test.h264

The command above activates the left camera (sensor-id=0), uses a combination of nvcamerasrc, nvvidconv, and omxh264enc to open control options and different stages of the image pipeline, and records a video at 50 frames per second into an H264 video file at a bitrate of 8Mb.

Controls Available with nvcamerasrc

To add a control of this species to a gstreamer pipeline, you insert it before the bang after the nvcamerasrc, for example:

gst-launch-1.0 -e nvcamerasrc sensor-id=0 wbmode=5 ! \
 ...

Default settings are given in bold for each control option.

 
wbmode=0
wbmode=1
wbmode=2
wbmode=3
wbmode=4
wbmode=5
wbmode=6
wbmode=7
wbmode=8
wbmode=9

 
color-effect=1
color-effect=2
color-effect=3
color-effect=4
color-effect=5
color-effect=6
color-effect=7

 
auto-exposure=1
auto-exposure=2
auto-exposure=3
auto-exposure=4
auto-exposure=5

 
flash=0
flash=1
flash=2
flash=3

 
flicker=0
flicker=1
flicker=2
flicker=3

 
contrast=x

 
saturation=x

 
tnr-strength=x

 
tnr-mode=0
tnr-mode=1
tnr-mode=2

 
edge-enhancement=x

 
trigger=1
trigger=2

 
intent=1
intent=2
intent=3
intent=4
intent=5

 
sensor-id=n

 
enable-exif=n

 
enable-meta=n

 
aeRegion=(t,l,b,r)

 
wbRegion=(t,l,b,r)

 
fpsRange=(l,h)

 
exposure-time=x


 
wbManualMode=0
wbManualMode=1
wbManualMode=2
wbManualMode=3


 
wbGains=(r,gr,gb,b)


 
stitchConfig=(id,t,l,b,r)

 
callback=a

 
dump-bayer=n

 
num-sensors

 
orientation

white balance
off GST_NVCAM_WB_MODE_OFF
auto GST_NVCAM_WB_MODE_AUTO
incandescent GST_NVCAM_WB_MODE_INCANDESCENT
fluorescent GST_NVCAM_WB_MODE_FLUORESCENT
warm-fluorescent GST_NVCAM_WB_MODE_WARM_FLUORESCENT
daylight GST_NVCAM_WB_MODE_DAYLIGHT
cloudy-daylight GST_NVCAM_WB_MODE_CLOUDY_DAYLIGHT
twilight GST_NVCAM_WB_MODE_TWILIGHT
shade GST_NVCAM_WB_MODE_SHADE
manual GST_NVCAM_WB_MODE_MANUAL

color-effect
off GST_NVCAM_COLOR_EFFECT_OFF
mono GST_NVCAM_COLOR_EFFECT_MONO
negative GST_NVCAM_COLOR_EFFECT_NEGATIVE
solarize GST_NVCAM_COLOR_EFFECT_SOLARIZE
sepia GST_NVCAM_COLOR_EFFECT_SEPIA
posterize GST_NVCAM_COLOR_EFFECT_POSTERIZE
aqua GST_NVCAM_COLOR_EFFECT_AQUA

auto-exposure
off GST_NVCAM_AUTO_EXPOSURE_OFF
on GST_NVCAM_AUTO_EXPOSURE_ON
OnAutoFlash GST_NVCAM_AUTO_EXPOSURE_AUTOFLASH
OnAlwaysFlash GST_NVCAM_AUTO_EXPOSURE_ALWAYSFLASH
OnFlashRedEye GST_NVCAM_AUTO_EXPOSURE_AUTO_RED_EYE

flash
off GST_NVCAM_FLASH_OFF
on GST_NVCAM_FLASH_ON
torch GST_NVCAM_FLASH_TORCH
auto GST_NVCAM_FLASH_AUTO

flicker
off GST_NVCAM_FLICKER_OFF
50Hz GST_NVCAM_FLICKER_50HZ
60Hz GST_NVCAM_FLICKER_60HZ
auto GST_NVCAM_FLICKER_AUTO

contrast
x is a float. Range 0 - 1 Default 0

saturation
x is a float. Range 0 - 2 Default 1

tnr-strength (temporal noise reduction strength)
x is a float. Range 0 - 1 Default 0

tnr-mode (temporal noise reduction mode)
NoiseReduction_Off GST_NVCAM_NR_OFF
NoiseReduction_Fast GST_NVCAM_NR_FAST
NoiseReduction_HighQuality GST_NVCAM_NR_HIGHQUALITY

edge-enhancement
x is a float. Range 0 - 1 Default 1

trigger
idle GST_NVCAM_TRIGGER_IDLE
start GST_NVCAM_TRIGGER_START

intent
preview GST_NVCAM_INTENT_PREVIEW
still GST_NVCAM_INTENT_STILL
video GST_NVCAM_INTENT_VIDEO
video-snapshot GST_NVCAM_INTENT_VIDEO_SNAPSHOT
zsl GST_NVCAM_INTENT_ZSL

sensor-id
n is an integer. Range 0 - 255 (0 - 1 on Spiri Mu) Default 0

enable-exif
n is a Boolean. Default false

enable-meta
n is a Boolean. Default false

aeRegion (autoexposure region of interest)
GArray, with values of ROI coordinates (top,left,bottom,right)

wbRegion (white balance region of interest)
GArray, with values of ROI coordinates (top,left,bottom,right)

fpsRange
String, with values of FPS Range (low,high)

exposure-time
x is a float. Range: 0 - 3.402823e+38 Default 0.033
This has effect only when Exposure mode is off.

wbManualMode
off GST_NVCAM_WB_MANUAL_OFF
reset GST_NVCAM_WB_MANUAL_RESET
restore GST_NVCAM_WB_MANUAL_RESTORE
external-gains GST_NVCAM_WB_MANUAL_EXTGAINS
This has effect only when wbMode is manual.

wbGains
GArray, with values of WB gains (red,green_r,green_b,blue)
This has effect only when wbMode is manual.

stitchConfig (set stitching windows)
GArray, with values (sensor_id,top,left,bottom,right)

callback (set user callback)
Provide address of GstNvCamSrcCallbacks, type struct.

dump-bayer
n is a Boolean. Default false

num-sensors
Returns GArray containing number of sensors {usb,csi}.

orientation
Returns sensor orientation value as integer. Range: 0 - 360