VisionWorks Toolkit Reference

September 29, 2015 | 1.0 Release

 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
stable/nvmedia_camera/nvmedia_camera_user_guide.md
Go to the documentation of this file.
1 <!-- Copyright (c) 2015, NVIDIA CORPORATION. All rights reserved. -->
2 
3 @defgroup nvx_sample_nvmedia_camera (Vibrante) NvMedia Camera Capture Sample App
4 @brief NvMedia Camera Capture Sample user guide.
5 @ingroup nvx_samples
6 @{
7 
8 <a name="Introduction">
9 ## Introduction ##
10 
11 @note This sample is available for Vibrante platform only.
12 
13 `nvx_sample_nvmedia_camera` demonstrates frame grabbing from 1, 2, or 4 CSI cameras
14 with NvMedia API and basic VisionWorks-NvMedia interop facilities. As a basic
15 VisionWorks processing step, histogram equalization is used. Histogram equalization
16 is applied to inner sub-rectangle only to make the effect of equalization more
17 obvious. The sample is available for Vibrante platform only and is tested with
18 four MAXIM DT0614 (OV10635) CSI cameras.
19 
20 After VisionWorks installation, `nvx_sample_nvmedia_camera` is installed in the
21 following directory:
22 
23  /usr/share/visionworks/sources/samples/nvmedia_camera
24 
25 For the steps to build sample applications, see the
26 @ref nvx_sample_building_linux section.
27 
28 The sample organization on the global level is illustrated by the flowchart.
29 
30  [Capture2D step]
31  |
32  [IPA step]
33  |
34  [PreProcess step]
35  / \
36  / \
37  / \
38  [ISP step] ... [ISP step]
39  | |
40  [PostISP step] ... [PostISP step]
41  | |
42  [I2D step] ... [I2D step]
43  \ /
44  \ /
45  \ /
46  [PostProcess step]
47  |
48  [Histogram Equalization]
49  |
50  [Rendering]
51 
52  IPA = Image Processing Accelerator
53  ISP = Image Signal Processing
54  IPP = Image Processing Pipeline
55 
56 The sample builds the chain of hardware-based NvMedia image processing steps that
57 are executed in a dedicated thread for each active camera. Thread communication
58 is based on queues without actual data copying. The Capture2D, IPA, PreProcess and
59 PostProcess steps are common for all cameras. The PreProcess step splits captured
60 image to per-camera frames, and the PostProcess step joins all these frames back
61 to a single image. Communication between the PostProcess step and VisionWorks is
62 implemented with EGLStream EGL extension. The main thread implements histogram
63 equalization and then rendering to exclude EGL and OpenVX context sharing between
64 threads.
65 
66 File layout:
67 
68 - `main_nvmedia_camera.cpp` implements EGL, OpenGL ES, CUDA consumer and
69  VisionWorks initialization, computer vision, and rendering steps.
70 - `capture2d.cpp` implements NvMedia pipeline and camera initialization, plus all
71  NvMedia-based steps.
72 - `ics_*.c` files contain camera drivers and code for their control.
73 - `*_utils.c` files provide different utilities for buffer management, logging, and
74  other supplementary routings.
75 
76 ## Attaching the Cameras ##
77 
78 Cameras must be attached to the correct port to work. The following images
79 illustrate the camera connections.
80 
81 
82 @note There are multiple CSI connectors on the board. You must connect cameras
83 in the correct order:
84  - For Jetson Pro, connect in ascending order starting from connector 0.
85  - For Drive PX, attach the connectors in reverse order as shown in the
86  Drive PX picture below.
87 
88 @note For more details, see the *Platform Quick Start* for your board.
89 
90 ### Drive PX Camera Connections
91 
92 NVIDIA Drive PX provides multiple video and camera ports. Before using these
93 cameras with the NvMedia sample applications, you must attach the cameras to
94 the ports in a specific order. If you fail to do so, NvMedia raises errors.
95 
96 @warning Before connecting/disconnecting cameras to/from the platform, remove
97 power. Failure to do so may damage the platform.
98 
99 ![](docs-user/images/emb_vib_drivepx_front.jpg)
100 
101 #### Drive PX Camera Interfaces
102 
103 Drive PX provides GMSL, USB, and Ethernet camera interfaces. The GMSL camera
104 interfaces:
105 
106 - Provide 12 simultaneous GMSL camera inputs
107 - Route camera data to both Tegras
108 - Control any camera from either Tegra
109 - Synchronize cameras within each group
110 
111 #### Mapping Connectors to Tegra Chips
112 
113 Each GMSL camera group can be routed to one or both Tegra chips via a GMSL
114 Deserializer.
115 
116 ![](docs-user/images/emb_nvmedia_drivepx_cam_to_tegras.jpg)
117 
118 #### Connecting Cameras to Drive PX
119 
120 When you connect cameras to a specific camera group, you must attach the
121 cameras in sequential order. For example, within Group A:
122 
123 - Attach the first camera to A0.
124 - If used, attach the second camera to A1.
125 - If used, attach the second camera to A2.
126 - If used, attach the second camera to A3.
127 
128 If you fail to attach cameras in this order, NvMedia generates an error message.
129 
130 ![](docs-user/images/emb_nvmedia_drivepx_cam_connector_map.jpg)
131 
132 #### Default Aggregator Link Mapping
133 
134 The following diagram shows how the digitized camera pictures are aggregated
135 into a frame, where the image from the first camera appears first in the frame
136 and the image from the last camera appears last in the frame. The frame size
137 changes depending on how many cameras are connected.
138 
139 All the sample applications that process images provide a aggregate `n` option
140 to specify the number of aggregated images in the frame. In this option, `n`
141 maps as follows:
142 
143 - n=1 maps to link0
144 - n=2 maps to link0 and link1
145 - etc.
146 - n=4 maps to all links
147 
148 The number of cameras connected must match the number specified in the aggregate
149 option.
150 
151 ![](docs-user/images/emb_nvmedia_drivepx_cam_agg_link_map.jpg)
152 
153 ### Jetson TK1 Pro Camera Connections
154 
155 ![](docs-user/images/jetson-tk1-pro.png)
156 
157 ### E2580 Camera Connections
158 
159 ![](docs-user/images/E2580_Camera_Connections.jpg)
160 
161 <a name="Executing">
162 ## Executing the NvMedia Camera Sample ##
163 
164 - On Jetson TK1 Pro with 2 cameras, execute:
165 
166  $ ./nvx_sample_nvmedia_camera -c data/cameras/dvp-ov10635-yuv422-ab.ini -n 2
167 
168 - On Drive PX A00 / Drive PX B00, execute:
169 
170  $ ./nvx_sample_nvmedia_camera -c data/cameras/dvp-ov10635-yuv422-ab-e2379.ini -n 2
171 
172 - On E2580, execute:
173 
174  $ ./nvx_sample_nvmedia_camera -c data/cameras/dvp-ov10635-yuv422-ef-e2580.ini -n 2
175 
176 ### Command Line Options ###
177 
178 This topic provides a list of supported options and the values they consume.
179 
180 #### \-c, \--camera ####
181 - Parameter: [Camera hardware configuration name]
182 - Description: Specifies the configuration file that describes the current
183  camera setup.
184 
185 - Usage: \--camera="cameras/dvp-ov10635-yuv422-ab.ini"
186 
187 @warning Do not modify config files. An incorrect value of any property leads
188 to cameras startup failures.
189 
190 #### \-p, \--processor ####
191 - Parameter: [2D processor hardware configuration name]
192 - Description: Specifies the configuration file that describes the current
193  2D processor configuration.
194 - Usage: \--processor="cameras/2d-processor-default.ini"
195 
196 #### \-n, \--camera_number ####
197 - Parameter: [Number of connected cameras]
198 - Description: Specifies the number of connected cameras. 1, 2, or 4 cameras are
199  supported.
200 - Usage: \--camera_number=4
201 
202 #### \-h, \--help ####
203 - Description: Prints the help message.
204 
205 ### Operational Keys ###
206 - Use `Space` to toggle histogram equalization mode.
207 - Use `ESC` to close the sample.
208 
209 @}
Range< T > all()
Creates a range that includes all points.
Definition: Range.hpp:163