Software Development Kit

 //  previous: How does it work?  //  next: MxPEG Frame/Stream Format

Finding the right streaming parameters

The canonical way to retrieve an MxPEG stream from the camera is via an HTTP API call like the following:

curl http://<your.camera.ip>/control/faststream.jpg?stream=MxPEG&needlength&fps=6

Replace curl with your preferred HTTP agent.

Parameters for faststream.jpg

These parameters are available for faststream.jpg (remember, in V2.2.1.4 of the camera software):

Parameter=Default Values Explanation
help   Help
This overview.
stream=full full
MxPEG
mxg		 Stream Type
Image data in stream:
full: full JPEG images
MxPEG: MOBOTIX optimized JPEG
mxg: MxPEG Clipfile; not server push
needlength   Need Content-Length
Send HTTP content-length for every frame in server push stream.
Note: This option is not useful for browsers.
jpheaderupdate=0 0..1000 Frames between tables refreshs
Table refresh count. 0: off, 1: every frame, 2: every second frame, ...
jpheaderrefresh=10 0..60 Seconds between table refreshs
Table refresh time. 0: off, 1: every second, 2: every second second, ...
fps=1  Escaped string Frames per Second
Frame rate of streamed images:
e.g. '3.0' streaming with 3 frames per second. Set to 0 for maximum rate.
framecount=0 0.. Frame Counter
Amount of images delivered before stream stops (0=infinite).
fip=10.0.0.0  Escaped string Factory IP
Will only deliver an image if the camera has this factory IP address.
error=picture picture
empty
content
current		 Error Handling
Sets the error handling options in case no image is available:
picture: returns the "No frame available!" image
empty: returns nothing
content: returns only the content type
current: returns the current.jpg image
html   HTML Page With Stream
Output HTML page including stream.

This table is contained in Chapter 56 ("CGI Parameters of the MOBOTIX camera") of the Reference Manual or in the identical help page http://<your.camera.ip>/help/help?cgi-image#faststream.jpg .

Controlling other settings through the HTTP API

The relevant settings are listed in Section 55.2.19 ("Parameters for the mxpegparam Section") of the Reference Manual or in the identical help page http://<your.camera.ip>/help/help?cgi-remotecontrol#mxpegparam :

Parameter Name in Dialog Possible Values Default Value(s)
Camera Selection
camera Camera Selection right, left, auto auto
Image Size
size Image Size 160x120, 320x240, 640x480, 1280x960, customize, 640x240 640x480
Brightness
brightness Brightness -10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 0 0
Sharpness
sharpen Sharpness 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 4 4
JPEG Quality
quality JPEG Quality 10, 20, 30, 40, 50, 60, 70, 80, 90 70
MxPEG
motionjpeg MxPEG disable, enable enable
mxpeg_cyclic Cyclic Image Refresh 0 .. 100 8
mxpeg_minchange Minimum MCU Change 0 .. 100 10
mxpeg_sw2full Switch to Full Image 0 .. 100 60
Exposure Field
ca_exp_window_type Measurement Field all, quarter, center, spot, top, middle, bottom, right, vertical, left, right_left, extra all all
ca_exp_window_draw Show Field off, on, histogram_inside, histogram_outside, out_histogram_inside, out_histogram_outside, jpeg_histogram off off

Control parameters are set by retrieving, e.g.:

http://<your.camera.ip>/control/control?set&quality=80&mxpeg_cyclic=4&mxpeg_minchange=2

The parameters mxpeg_minchange and mxpeg_cyclic are related to the aformentioned update procedure.

mxpeg_minchange is the threshold (in percent of change) above which a tile will be included in the next MxPEG frame.

Setting mxpeg_cyclic to a value > 0 forces the encoder to include tiles in the MxPEG frame whose amount of change is below the threshold. It scans through the YUV image and includes in each unit of time (which is approx. 1/12.5 s here) mxpeg_cyclic % of the unchanged tiles. This means that at a rate of 4 fps and an mxpeg_cyclic value of 8 (the default value), an amount of 12.5/4 * 8% = 25% of the otherwise unchanged tiles will be transmitted. After one second, all tiles of the complete image will be included in the transmitted MxPEG frames even if no change is detected in the image. The same is true for any other frame rate.

As always, reality is slightly more complicated. The following tables show the relationship between percentage of MCUs updated per unit of mxpeg_cyclic (again, for M10 models):

320x240 (300 MCUs)
frames per second (nominal) seconds per frame (nominal) % MCUs updated per % cyclic refresh cyclic needed for full update every second cyclic needed for full update every frame frames per second (actual) seconds per frame (actual)
0.5 2 23 n/a 4.3 0.5 2.000
1 1 12 8.3 8.3 1.0 1.000
2 0.5 7 7.5 14.3 1.9 0.526
3 0.33 5 6.5 20.0 3.1 0.323
4 0.25 4 5.8 25.0 4.3 0.233
6 0.17 3 6.2 33.3 5.4 0.185
12 0.08 2 4.6 50.0 10.8 0.093
20 0.05 2 2.3 50.0 21.8 0.046
640x480 (1200 MCUs)
frames per second (nominal) seconds per frame (nominal) % MCUs updated per % cyclic refresh cyclic needed for full update every second cyclic needed for full update every frame frames per second (actual) seconds per frame (actual)
0.5 2 23 n/a 4.3 0.5 2.000
1 1 12 8.3 8.3 1.0 1.000
2 0.5 7 7.5 14.3 1.9 0.526
3 0.33 5 6.9 20.0 2.9 0.345
4 0.25 4 6.8 25.0 3.7 0.270
6 0.17 3 6.0 33.3 5.6 0.179
12 0.08 2 4.5 50.0 11.1 0.090

For megapixel images, still other values for the % MCU / mxpeg_cyclic ratio are in place: it is 9, 5, 3, and 2 for fps of 0.5, 1, 2 and 4, respectively.

But as a rule of thumb for everyday applications (640x480 or 320x240 resolutions, frame rates above 1 fps) keep in mind:

With the default mxpeg_cyclic value of 8, it takes less than a second until the whole image is restored.

This means that if you want to jump to a certain point in time in the middle of an MxPEG recording, it should be sufficient to go 1 s back in time and keep the tiles coming in. At the specified point in time, the complete image should be available by virtue of cyclic update.

Please note that mxpeg_cyclic will be discontinued in future software versions. It will be replaced by a parameter that is easier to use: You will be able to specify the time interval within which all tiles are updated cyclically.

Instead of I-frames...

With the current MxPEG implementation, there is no way to tell the codec to include a full JPEG frame, say, every second or every 20 frames. Therefore, there's no I-Frame concept known from other codecs. But the way sketched above, jumping back one second and start decoding, may serve as a practical workaround.

Let's close this lengthy section with a brief discussion of some of the other control and faststream.jpg parameters.

Note: Some parameters may only be set per camera, i.e., changing them influences every stream that is retrieved. Examples are size and quality. These settings are changed using control. Examples for per-stream settings are fps and needlength.

mxpeg_sw2full (control parameter) tells the codec which percentage of tiles needs to have changed in the YUV image before it switches to transmitting full images without the bitmask.

jpheaderupdate and jpheaderrefresh (faststream.jpg parameter) tell the codec to regularly include updated tables in the MxPEG frames. This of course increases the bandwidth/storage need of the frame.

Note: The Huffman tables are always the same (they don't tend to change with every SW version). The quantization tables depend on the selected JPEG quality. If you change the quality while retrieving a stream, the old tables may not be valid any more. If your application continues to use them there might be visual artifacts.

Finally, needlength (faststream.jpg parameter) tells the codec to send also the content-length when in stream=MxPEG mode.

 //  previous: How does it work?  //  next: MxPEG Frame/Stream Format

Copyright (c) 2005-2007, MOBOTIX AG. All rights reserved.