Initialize EO::current_frame_idx_m in constructor
[tidl/tidl-api.git] / docs / source / example.rst
1 .. _examples:
3 ********
4 Examples
5 ********
7 .. list-table:: TIDL API Examples
8    :header-rows: 1
9    :widths: 12 43 20 25
11    * - Example
12      - Description
13      - Compute cores
14      - Input image
15    * - one_eo_per_frame
16      - Processes a single frame with one :term:`EO` using the j11_v2 network. Throughput is increased by distributing frame processing across EOs. Refer :ref:`use-case-1`.
17      - EVE or C66x
18      - Pre-processed image read from file.
19    * - two_eo_per_frame
20      - Processes a single frame with an :term:`EOP` using the j11_v2 network to reduce per-frame processing latency. Also increases throughput by distributing frame processing across EOPs. The EOP consists of two EOs. Refer :ref:`use-case-2`.
21      - EVE and C66x (network is split across both EVE and C66x)
22      - Pre-processed image read from file.
23    * - two_eo_per_frame_opt
24      - Builds on ``two_eo_per_frame``. Adds double buffering to improve performance. Refer :ref:`use-case-3`.
25      - EVE and C66x (network is split across both EVE and C66x)
26      - Pre-processed image read from file.
28    * - imagenet
29      - Classification example
30      - EVE or C66x
31      - OpenCV used to read input image from file or capture from camera.
32    * - segmentation
33      - Pixel level segmentation example
34      - EVE or C66x
35      - OpenCV used to read input image from file or capture from camera.
36    * - ssd_multibox
37      - Object detection
38      - EVE and C66x (network is split across both EVE and C66x)
39      - OpenCV used to read input image from file or capture from camera.
40    * - classification
41      - Classification example, called from the Matrix GUI.
42      -
43      - OpenCV used to read input image from file or capture from camera.
44    * - layer_output
45      - Illustrates using TIDL APIs to access output buffers of intermediate :term:`layers<Layer>` in the network.
46      - EVE or C66x
47      - Pre-processed image read from file.
48    * - test
49      - This example is used to test pre-converted networks included in the TIDL API package (``test/testvecs/config/tidl_models``). When run without any arguments, the program ``test_tidl`` will run all available networks on the C66x DSPs and EVEs available on the SoC. Use the ``-c`` option to specify a single network. Run ``test_tidl -h``  for details.
50      - C66x and EVEs (if available)
51      - Pre-processed image read from file.
53 The included examples demonstrate three categories of deep learning networks: classification, segmentation and object detection.  ``imagenet`` and ``segmentation`` can run on AM57x processors with either EVE or C66x cores.  ``ssd_multibox`` requires AM57x processors with both EVE and C66x. The examples are available at ``/usr/share/ti/tidl/examples`` on the EVM file system and in the linux devkit.
55 The performance numbers were obtained using:
57 * `AM574x IDK EVM`_ with the Sitara `AM5749`_ Processor - 2 Arm Cortex-A15 cores running at 1.0GHz, 2 EVE cores at 650MHz, and 2 C66x cores at 750MHz.
58 * `Processor SDK Linux`_ v5.1 with TIDL API v1.1
60 For each example, device processing time, host processing time,
61 and TIDL API overhead is reported.
63 * **Device processing time** is measured on the device, from the moment processing starts for a frame till processing finishes.
64 * **Host processing time** is measured on the host, from the moment ``ProcessFrameStartAsync()`` is called till ``ProcessFrameWait()`` returns in user application.  It includes the TIDL API overhead, the OpenCL runtime overhead, and the time to copy user input data into padded TIDL internal buffers. ``Host processing time = Device processing time + TIDL API overhead``.
67 Imagenet
68 --------
70 The imagenet example takes an image as input and outputs 1000 probabilities.
71 Each probability corresponds to one object in the 1000 objects that the
72 network is pre-trained with.  The example outputs top 5 predictions for a given input image.
74 The following figure and tables shows an input image, top 5 predicted
75 objects as output, and the processing time on either EVE or C66x.
77 .. image:: ../../examples/test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
78    :width: 600
81 ==== ==============
82 Rank Object Classes
83 ==== ==============
84 1    tabby
85 2    Egyptian_cat
86 3    tiger_cat
87 4    lynx
88 5    Persian_cat
89 ==== ==============
91 =======   ====================== ==================== ============
92 Device    Device Processing Time Host Processing Time API Overhead
93 =======   ====================== ==================== ============
94 EVE       106.5 ms               107.9 ms             1.37 %
95 C66x      117.9 ms               118.7 ms             0.93 %
96 =======   ====================== ==================== ============
98 The :term:`network<Network>` used in the example is jacintonet11v2. It has
99 14 layers. Input to the network is RGB image of 224x224. Users can specify whether to run the network on EVE or C66x.
101 The example code sets ``buffer_factor`` to 2 to create duplicated
102 ExecutionObjectPipelines with identical ExecutionObjects to
103 perform double buffering, so that host pre/post-processing can be overlapped
104 with device processing (see comments in the code for details).
105 The following table shows the loop overall time over 10 frames
106 with single buffering and double buffering,
107 ``./imagenet -f 10 -d <num> -e <num>``.
109 .. list-table:: Loop overall time over 10 frames
110    :header-rows: 1
112    * - Device(s)
113      - Single Buffering (buffer_factor=1)
114      - Double Buffering (buffer_factor=2)
115    * - 1 EVE
116      - 1744 ms
117      - 1167 ms
118    * - 2 EVEs
119      - 966 ms
120      - 795 ms
121    * - 1 C66x
122      - 1879 ms
123      - 1281 ms
124    * - 2 C66xs
125      - 1021 ms
126      - 814 ms
128 .. note::
129     The predicitions reported here are based on the output of the softmax
130     layer in the network, which are not normalized to the real probabilities.
132 Segmentation
133 ------------
135 The segmentation example takes an image as input and performs pixel-level
136 classification according to pre-trained categories.  The following figures
137 show a street scene as input and the scene overlaid with pixel-level
138 classifications as output: road in green, pedestrians in red, vehicles
139 in blue and background in gray.
141 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-972355.jpeg
142    :width: 600
144 .. image:: images/pexels-photo-972355-seg.jpg
145    :width: 600
147 The :term:`network<Network>` used in the example is jsegnet21v2. It has
148 26 layers.  Users can specify whether to run the network on EVE or C66x.
149 Input to the network is RGB image of size 1024x512.  The output is 1024x512
150 values, each value indicates which pre-trained category the current pixel
151 belongs to.  The example will take the network output, create an overlay,
152 and blend the overlay onto the original input image to create an output image.
153 From the reported time in the following table, we can see that this network
154 runs significantly faster on EVE than on C66x.
156 =======     ====================== ==================== ============
157 Device      Device Processing Time Host Processing Time API Overhead
158 =======     ====================== ==================== ============
159 EVE         251.8 ms               254.2 ms             0.96 %
160 C66x        812.7 ms               815.0 ms             0.27 %
161 =======     ====================== ==================== ============
163 The example code sets ``buffer_factor`` to 2 to create duplicated
164 ExecutionObjectPipelines with identical ExecutionObjects to
165 perform double buffering, so that host pre/post-processing can be overlapped
166 with device processing (see comments in the code for details).
167 The following table shows the loop overall time over 10 frames
168 with single buffering and double buffering,
169 ``./segmentation -f 10 -d <num> -e <num>``.
171 .. list-table:: Loop overall time over 10 frames
172    :header-rows: 1
174    * - Device(s)
175      - Single Buffering (buffer_factor=1)
176      - Double Buffering (buffer_factor=2)
177    * - 1 EVE
178      - 5233 ms
179      - 3017 ms
180    * - 2 EVEs
181      - 3032 ms
182      - 3015 ms
183    * - 1 C66x
184      - 10890 ms
185      - 8416 ms
186    * - 2 C66xs
187      - 5742 ms
188      - 4638 ms
190 .. _ssd-example:
192 SSD
193 ---
195 SSD is the abbreviation for Single Shot multi-box Detector.
196 The ssd_multibox example takes an image as input and detects multiple
197 objects with bounding boxes according to pre-trained categories.
198 The following figures show another street scene as input and the scene
199 with recognized objects boxed as output: pedestrians in red,
200 vehicles in blue and road signs in yellow.
202 .. image:: ../../examples/test/testvecs/input/roads/pexels-photo-378570.jpeg
203    :width: 600
205 .. image:: images/pexels-photo-378570-ssd.jpg
206    :width: 600
208 The network we ran in this category is jdenet_ssd, which has 43 layers.
209 Input to the network is RGB image of size 768x320.  Output is a list of
210 boxes (up to 20), each box has information about the box coordinates, and
211 which pre-trained category that the object inside the box belongs to.
212 The example will take the network output, draw boxes accordingly,
213 and create an output image.
214 The network can be run entirely on either EVE or C66x.  However, the best
215 performance comes with running the first 30 layers as a group on EVE
216 and the next 13 layers as another group on C66x.
217 Our end-to-end example shows how easy it is to assign a :term:`Layer Group` id
218 to an :term:`Executor` and how easy it is to construct an :term:`ExecutionObjectPipeline` to connect the output of one *Executor*'s :term:`ExecutionObject`
219 to the input of another *Executor*'s *ExecutionObject*.
221 ========      ====================== ==================== ============
222 Device        Device Processing Time Host Processing Time API Overhead
223 ========      ====================== ==================== ============
224 EVE+C66x      169.5ms                172.0ms              1.68 %
225 ========      ====================== ==================== ============
227 The example code sets ``pipeline_depth`` to 2 to create duplicated
228 ExecutionObjectPipelines with identical ExecutionObjects to
229 perform pipelined execution at the ExecutionObject level.
230 The side effect is that it also overlaps host pre/post-processing
231 with device processing (see comments in the code for details).
232 The following table shows the loop overall time over 10 frames
233 with pipelining at ExecutionObjectPipeline level
234 versus ExecutionObject level.
235 ``./ssd_multibox -f 10 -d <num> -e <num>``.
237 .. list-table:: Loop overall time over 10 frames
238    :header-rows: 1
240    * - Device(s)
241      - pipeline_depth=1
242      - pipeline_depth=2
243    * - 1 EVE + 1 C66x
244      - 2900 ms
245      - 1735 ms
246    * - 2 EVEs + 2 C66xs
247      - 1630 ms
248      - 1408 ms
250 Running Examples
251 ----------------
253 The examples are located in ``/usr/share/ti/tidl/examples`` on
254 the EVM file system.  **Each example needs to be run in its own directory** due to relative paths to configuration files.
255 Running an example with ``-h`` will show help message with option set.
256 The following listing illustrates how to build and run the examples.
258 .. code-block:: shell
260    root@am57xx-evm:~/tidl-api/examples/imagenet# ./imagenet
261    Input: ../test/testvecs/input/objects/cat-pet-animal-domestic-104827.jpeg
262    frame[  0]: Time on EVE0: 106.50 ms, host: 107.96 ms API overhead: 1.35 %
263    1: tabby
264    2: Egyptian_cat
265    3: tiger_cat
266    4: lynx
267    5: Persian_cat
268    Loop total time (including read/write/opencv/print/etc):  202.6ms
269    imagenet PASSED
271    root@am57xx-evm:~/tidl-api/examples/segmentation# ./segmentation
272    Input: ../test/testvecs/input/000100_1024x512_bgr.y
273    frame[  0]: Time on EVE0: 251.74 ms, host: 258.02 ms API overhead: 2.43 %
274    Saving frame 0 to: frame_0.png
275    Saving frame 0 overlayed with segmentation to: overlay_0.png
276    frame[  1]: Time on EVE0: 251.76 ms, host: 255.79 ms API overhead: 1.58 %
277    Saving frame 1 to: frame_1.png
278    Saving frame 1 overlayed with segmentation to: overlay_1.png
279    ...
280    frame[  8]: Time on EVE0: 251.75 ms, host: 254.21 ms API overhead: 0.97 %
281    Saving frame 8 to: frame_8.png
282    Saving frame 8 overlayed with segmentation to: overlay_8.png
283    Loop total time (including read/write/opencv/print/etc):   4809ms
284    segmentation PASSED
286    root@am57xx-evm:~/tidl-api/examples/ssd_multibox# ./ssd_multibox
287    Input: ../test/testvecs/input/preproc_0_768x320.y
288    frame[  0]: Time on EVE0+DSP0: 169.44 ms, host: 173.56 ms API overhead: 2.37 %
289    Saving frame 0 to: frame_0.png
290    Saving frame 0 with SSD multiboxes to: multibox_0.png
291    Loop total time (including read/write/opencv/print/etc):  320.2ms
292    ssd_multibox PASSED
295 Image input
296 ^^^^^^^^^^^
298 The image input option, ``-i <image>``, takes an image file as input.
299 You can supply an image file with format that OpenCV can read, since
300 we use OpenCV for image pre/post-processing.  When ``-f <number>`` option
301 is used, the same image will be processed repeatedly.
303 Camera (live video) input
304 ^^^^^^^^^^^^^^^^^^^^^^^^^
306 The input option, ``-i camera<number>``, enables live frame inputs
307 from camera.  ``<number>`` is the video input port number
308 of your camera in Linux.  Use the following command to check video
309 input ports.  The number defaults to ``1`` for TMDSCM572X camera module
310 used on AM57x EVMs.  You can use ``-f <number>`` to specify the number
311 of frames you want to process.
313 .. code-block:: shell
315   root@am57xx-evm:~# v4l2-ctl --list-devices
316   omapwb-cap (platform:omapwb-cap):
317         /dev/video11
319   omapwb-m2m (platform:omapwb-m2m):
320         /dev/video10
322   vip (platform:vip):
323         /dev/video1
325   vpe (platform:vpe):
326         /dev/video0
329 Pre-recorded video (mp4/mov/avi) input
330 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
332 The input option, ``-i <name>.{mp4,mov,avi}``, enables frame inputs from
333 pre-recorded video file in mp4, mov or avi format.  If you have a video in
334 a different OpenCV-supported format/suffix, you can simply create a softlink
335 with one of the mp4, mov or avi suffixes and feed it into the example.
336 Again, use ``-f <number>`` to specify the number of frames you want to process.
338 Displaying video output
339 ^^^^^^^^^^^^^^^^^^^^^^^
341 When using video input, live or pre-recorded, the example will display
342 the output in a window using OpenCV.  If you have a LCD screen attached
343 to the EVM, you will need to kill the ``matrix-gui`` first in order to
344 see the example display window, as shown in the following example.
346 .. code-block:: shell
348   root@am57xx-evm:/usr/share/ti/tidl/examples/ssd_multibox# /etc/init.d/matrix-gui-2.0 stop
349   Stopping Matrix GUI application.
350   root@am57xx-evm:/usr/share/ti/tidl/examples/ssd_multibox# ./ssd_multibox -i camera -f 100
351   Input: camera
352   init done
353   Using Wayland-EGL
354   wlpvr: PVR Services Initialised
355   Using the 'xdg-shell-v5' shell integration
356   ... ...
357   root@am57xx-evm:/usr/share/ti/tidl/examples/ssd_multibox# /etc/init.d/matrix-gui-2.0 start
358   /usr/share/ti/tidl/examples/ssd_multibox
359   Removing stale PID file /var/run/matrix-gui-2.0.pid.
360   Starting Matrix GUI application.
363 .. _AM574x IDK EVM:  http://www.ti.com/tool/tmdsidk574
364 .. _AM5749: http://www.ti.com/product/AM5749/
365 .. _Processor SDK Linux: http://software-dl.ti.com/processor-sdk-linux/esd/AM57X/latest/index_FDS.html