Merge pull request #24 from hamishwillee/image_capture

hamishwillee · web-flow · commit f773c0fc0beb · 2018-04-24T10:16:51.000+10:00
Update information about support for image and video capture
diff --git a/en/guide/configuration_file.md b/en/guide/configuration_file.md
@@ -109,18 +109,54 @@ Example (Ubuntu):
 video0=http://127.0.0.1:8000/camera-def-uvc.xml
 ```
 
-### [imgcap]
+### [imgcap] {#imgcap}
+
+This section defines the *default* values used for image capture. With the exception of `location` it should be possible override the values over MAVLink using parameters defined in the [Camera Definition File](../guide/camera_definition_file.md).
+
+> **Note** At time of writing these default values cannot yet be overridden (see [#161](https://github.com/Dronecode/camera-streaming-daemon/issues/161)).
 
 Key | Description | Default
 -- | --- | ---
-`location` | The local path with write permission where captured images will be saved (usually the system-standard "Temp" directory) | -
+`width` | Width of the image to be captured in pixels. | Full width of camera frame for sensor type (i.e 1080P - 1920, 720P - 1280, etc.)
+`height` | Height of the image to be captured in pixels. | Full height of camera frame for sensor type (i.e 1080P - 1080, 720P - 720, etc).
+`format` | Image format (number). <br>Possible values:<ul><li>2 (Jpeg/<code>IMAGE_FILE_JPEG</code>)</li></ul>Notes:<ul><li>Currently only Jpeg is <a href="https://github.com/Dronecode/camera-streaming-daemon/issues/163">supported for image capture</a>.</li></ul> | 2 (JPEG).
+`location` | The local path with write permission where captured images will be saved (usually the system-standard "Temp" directory). The path should be accessible and writeable. | /tmp/
 
 Example:
 ```
 [imgcap]
 location=~/Temp/
 ```
 
+### [vidcap] {#vidcap}
+
+This section defines the *default* values used for video capture. With the exception of `location` it should be possible override the values over MAVLink using parameters defined in the [Camera Definition File](../guide/camera_definition_file.md).
+
+> **Note** At time of writing these default values cannot yet be overridden (see [#161](https://github.com/Dronecode/camera-streaming-daemon/issues/161)).
+
+Key | Description | Default
+--- | --- | ---
+`width` | Width of the video to be captured in pixels. | Full width of camera frame for sensor type (i.e 1080P - 1920, 720P - 1280, etc).
+`height` | Height of the video to be captured in pixels. | Full height of camera frame for sensor type (i.e 1080P - 1080, 720P - 720, etc).
+`framerate` | Camera framerate for video capture. | Default framerate queried from camera sensor (e.g. 25).
+`bitrate` | Bitrate of the encoded video data in KBps. Supported values: 1 - 2048000. | 512
+`encoder` | Encoder (number). <br>Possible values:<ul><li>3 (H.264/<code>VIDEO_CODING_AVC</code>)</li></ul>Notes:<ul><li>Currently only H.264 is <a href="https://github.com/Dronecode/camera-streaming-daemon/issues/168">supported for video capture</a>.</li></ul>  | 3 (AVC).
+`format` | Video file format (number). <br>Possible values:<ul><li>1 (Moving Pictures Expert Group 4/<code>VIDEO_FILE_MP4</code>)</li></ul>Notes:<ul><li>Currently only MP4 is <a href="https://github.com/Dronecode/camera-streaming-daemon/issues/169">supported for video capture</a>.</li></ul> | 1 (MP4)
+`location` | The local path with write permission where captured videos will be saved (usually the system-standard "Temp" directory). | -
+
+
+Example (Ubuntu):
+```
+[vidcap]
+width=640
+height=480
+framerate=25
+bitrate=1000
+encoder=3
+format=1
+location=/tmp/
+```
+
 
 ### [gazebo]
 
diff --git a/en/guide/overview.md b/en/guide/overview.md
@@ -16,7 +16,7 @@ CSD supports the following key features:
 * Automatically attaches [compatible cameras](#supported_cameras) connected to the Linux computer when it is started.
 * RTSP video streaming from *all* connected cameras (for consumption by GCS or other video players).
 * RTSP video stream advertising/discovery using Avahi.
-* [MAVLink Camera Protocol](#mavlink_support) support for up to 5 cameras, enabling image capture and storage, and querying/setting camera options. <!-- but not yet video capture - Mar 2018 -->
+* [MAVLink Camera Protocol](#mavlink_support) support for up to 5 cameras, enabling image/video capture and storage, and querying/setting camera options.
 * Gazebo simulated camera backend (so you can view video streams from within a simulated environment)!
 * Configurable back-end that can be extended to interface with new types of cameras and new front-end protocols.
 
@@ -42,16 +42,18 @@ Advanced configuration information about individual cameras is specified in [Cam
 
 ## MAVLink Camera Protocol Implementation {#mavlink_support}
 
-CSD implements the [MAVLink Camera Protocol](https://mavlink.io/en/protocol/camera.html) for image capture and getting/setting camera parameters and options. At time of writing (March 2018) video capture is not yet supported.
+CSD implements the [MAVLink Camera Protocol](https://mavlink.io/en/protocol/camera.html) for image and video capture and storage, and for getting/setting camera parameters and options.
 
 The MAVLink properties of CSD are specified in the *CSD Configuration File*:
 * The [\[mavlink\]](../guide/configuration_file.md#mavlink) section is used to specify the MAVLink destination UDP port, the broadcast address for heartbeat messages, and the system id (which should be set to match the autopilot).
 * The [\[uri\]](../guide/configuration_file.md#uri) section specifies the device to URI mapping for [Camera Definition File](../guide/camera_definition_file.md).
+* The [\[imgcap\]](../guide/configuration_file.md#imgcap) and [\[vidcap\]](../guide/configuration_file.md#vidcap) sections specify the *default settings* for image and video capture, respectively.
 
 Component IDs for each camera are allocated automatically and sequentially from [MAV_COMP_ID_CAMERA2](https://mavlink.io/en/messages/common.html#MAV_COMP_ID_CAMERA2) to [MAV_COMP_ID_CAMERA6](https://mavlink.io/en/messages/common.html#MAV_COMP_ID_CAMERA6) (inclusive) as cameras are connected (once all component ids are allocated further cameras are not addressable).
 
 **Limitations:**
 
 * At time of writing (March 2018) the camera protocol, and hence CSD, do not yet include a formal specification for managing or advertising RTSP video streams.
 * The MAVLink protocol supports up to 6 cameras in a single system (only 6 `component_id` values are defined). Currently only 5 cameras can be accessed via CSD (see [#142](https://github.com/intel/camera-streaming-daemon/issues/142)).
-* Video capture is not supported.
+* The default [image](../guide/configuration_file.md#imgcap) and [video](../guide/configuration_file.md#vidcap)
+capture settings cannot (yet) be overwritten using parameters/via a [Camera Definition File](../guide/camera_definition_file.md) (see [#161](https://github.com/Dronecode/camera-streaming-daemon/issues/161)).
