GoWebScan API
 All Classes Files Functions Variables Typedefs Macros Modules Pages
GoWebScanTileCombiner.h
Go to the documentation of this file.
1 /**
2 * @file GoWebScanTileCombiner.h
3 * @brief Declares a GoWebScanTileCombiner object.
4 *
5 * @internal
6 * Copyright (C) 2017-2018 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 
11 #ifndef GO_WEB_SCAN_TILE_COMBINER_H
12 #define GO_WEB_SCAN_TILE_COMBINER_H
13 
17 #include <kApi/Data/kArrayList.h>
18 
19 kBeginHeader()
20 
21 /**
22 * @class GoWebScanTileCombiner
23 * @extends kObject
24 * @ingroup GoWebScanSdk-Algorithms
25 * @brief Represents an algorithm for matching tiles received from different sources. Each source
26 * is represented by a combiner lane, which has a FIFO queue of received tiles. When a tile
27 * is received, the combiner logic decides whether to emit a frame (set of tiles that have
28 * the same position) or wait. A time threshold and a distance threshold must both be
29 * exceeded to cause a coherency violation. The primary consideration is time - when a lane
30 * has not received a frame within the specified time window, something has gone wrong and
31 * the lane should be disabled as soon as possible. But if the system reverses (no new tiles),
32 * and then runs forward again (new tiles when it catches up), a false coherency violation can
33 * be generated if time is the only criteria. A small distance coherency threshold is used to
34 * prevent these false violations.
35 */
37 
38 /**
39 * @struct GoWebScanTileCombinerParams
40 * @extends kValue
41 * @ingroup GoWebScanSdk-Algorithms
42 * @brief Represents parameters of the tile combiner algorithm.
43 */
45 {
46  k64s coherencyDistance; ///< Lane is disabled if the distance between the first undelivered tile and last undelivered tile exceed this threshold (mils).
47  k64s coherencyTime; ///< Lane is disabled if the time between the first undelivered tile and the last undelivered tile exceed this threshold (microseconds).
48  k64s breakDistance; ///< While the first undelivered tile and last undelivered tile have a position difference greater than this threshold, all combiner frames are dropped (mils).
49 
51 
52 /** Defines the signature for the handler for accepting the output dataset. */
53 typedef kStatus(kCall *GoWebScanTileCombinerDataFx)(kPointer context, k64s tileIndex, GoWebScanPipeMsg* tiles, kSSize laneCount, kSSize tileCount);
54 
55 /**
56 * Constructs a GoWebScanTileCombiner object.
57 *
58 * @public @memberof GoWebScanTileCombiner
59 * @param combiner Receives the constructed GoWebScanTileCombiner object.
60 * @param args Algorithm parameters.
61 * @param allocator Memory allocator (or kNULL for default).
62 * @return Operation status.
63 */
65 
66 /**
67 * Adds a lane to the combiner. A lane represents a unique source of tiles and is identified by
68 * the 4 element ID field in the tile message stamp.
69 *
70 * @public @memberof GoWebScanTileCombiner
71 * @param combiner GoWebScanTileCombiner object.
72 * @param msgId Message type ID.
73 * @param id1 Second element of lane ID.
74 * @param id2 Third element of lane ID.
75 * @param id3 Fourth element of lane ID.
76 * @return Operation status.
77 * @see GoWebScanMsgStamp
78 */
79 GoWebScanFx(kStatus) GoWebScanTileCombiner_AddLane(GoWebScanTileCombiner combiner, k32s msgId, k32s id1, k32s id2, k32s id3);
80 
81 /**
82 * Sets the handler for accepting the output data from the algorithm.
83 *
84 * @public @memberof GoWebScanTileCombiner
85 * @param combiner GoWebScanTileCombiner object.
86 * @param data Callback function
87 * @param context Receiver argument for callback.
88 * @return Operation status.
89 */
91 
92 /**
93 * Adds a tile message to the algorithm processing queue. The tile is added to the lane that
94 * corresponds to the message stamp ID.
95 *
96 * @public @memberof GoWebScanTileCombiner
97 * @param combiner GoWebScanTileCombiner object.
98 * @param msg Tile message to add.
99 * @return Operation status.
100 */
102 
103 /**
104 * Clears and relinquishes all lane tile queues.
105 *
106 * @public @memberof GoWebScanTileCombiner
107 * @param combiner GoWebScanTileCombiner object.
108 * @return Operation status.
109 */
111 
112 /**
113 * Gets the lane ID for a given lane index.
114 *
115 * @public @memberof GoWebScanTileCombiner
116 * @param combiner GoWebScanTileCombiner object.
117 * @param index Lane index.
118 * @param id0 Receives the first element of the lane ID.
119 * @param id1 Receives the second element of the lane ID.
120 * @param id2 Receives the third element of the lane ID.
121 * @param id3 Receives the fourth element of the lane ID.
122 * @return Operation status.
123 */
124 GoWebScanFx(kStatus) GoWebScanTileCombiner_LaneAt(GoWebScanTileCombiner combiner, kSSize index, k32s* id0, k32s* id1, k32s* id2, k32s* id3);
125 
126 kEndHeader()
127 #include <GoWebScanSdk/GoWebScanTileCombiner.x.h>
128 
129 #endif
k64s breakDistance
While the first undelivered tile and last undelivered tile have a position difference greater than th...
Definition: GoWebScanTileCombiner.h:48
k64s coherencyDistance
Lane is disabled if the distance between the first undelivered tile and last undelivered tile exceed ...
Definition: GoWebScanTileCombiner.h:46
kStatus GoWebScanTileCombiner_Construct(GoWebScanTileCombiner *combiner, const GoWebScanTileCombinerParams *args, kAlloc allocator)
Constructs a GoWebScanTileCombiner object.
Declares the GoWebScanPipeMsg class.
Essential GoWebScan declarations.
kStatus GoWebScanTileCombiner_SetDataHandler(GoWebScanTileCombiner combiner, GoWebScanTileCombinerDataFx data, kPointer context)
Sets the handler for accepting the output data from the algorithm.
kStatus GoWebScanTileCombiner_AddTile(GoWebScanTileCombiner combiner, GoWebScanPipeMsg msg)
Adds a tile message to the algorithm processing queue.
kStatus GoWebScanTileCombiner_LaneAt(GoWebScanTileCombiner combiner, kSSize index, k32s *id0, k32s *id1, k32s *id2, k32s *id3)
Gets the lane ID for a given lane index.
kStatus GoWebScanTileCombiner_Clear(GoWebScanTileCombiner combiner)
Clears and relinquishes all lane tile queues.
k64s coherencyTime
Lane is disabled if the time between the first undelivered tile and the last undelivered tile exceed ...
Definition: GoWebScanTileCombiner.h:47
Defines GoWebScan utility functions.
Represents parameters of the tile combiner algorithm.
Definition: GoWebScanTileCombiner.h:44
kStatus(kCall * GoWebScanTileCombinerDataFx)(kPointer context, k64s tileIndex, GoWebScanPipeMsg *tiles, kSSize laneCount, kSSize tileCount)
Defines the signature for the handler for accepting the output dataset.
Definition: GoWebScanTileCombiner.h:53
Base class for a msg that can be processed with a GoWebScanPipeTask and submitted to the GoWebScanPip...
kStatus GoWebScanTileCombiner_AddLane(GoWebScanTileCombiner combiner, k32s msgId, k32s id1, k32s id2, k32s id3)
Adds a lane to the combiner.
Represents an algorithm for matching tiles received from different sources. Each source is represente...