VisionWorks Toolkit Reference

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