Skip to content

Commit 2e60d9c

Browse files
jrobblejrobble
authored
Document FEED_FORWARD_ALL_TRACKS behavior. (#203)
1 parent bf2156b commit 2e60d9c

7 files changed

Lines changed: 221 additions & 40 deletions

File tree

‎docs/docs/Feed-Forward-Guide.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,3 +310,25 @@ a 1-to-1 correspondence with a MOG motion track.
310310
Refer to `runMogThenOcvFaceFeedForwardRegionTest()` in the
311311
[`TestSystemOnDiff`](https://github.com/openmpf/openmpf/blob/master/trunk/mpf-system-tests/src/test/java/org/mitre/mpf/mst/TestSystemOnDiff.java)
312312
class for a system test that demonstrates this behavior.
313+
314+
315+
# Feed Forward All Tracks
316+
317+
<div style="background-color:DeepSkyBlue"><p style="color:white; padding:5px"><b>EXPERIMENTAL:</b> This feature is not fully implemented.</p></div>
318+
319+
The default feed-forward behavior will result in generating one sub-job per track generated in the previous stage.
320+
Consider a scenario where you need to implement a tracking component that takes individual detections from a stage and
321+
groups them into tracks. That component needs to accept all tracks from the previous stage as an input to the same
322+
sub-job.
323+
324+
Setting `FEED_FORWARD_ALL_TRACKS` to true will result in generating one sub-job that contains all the tracks generated
325+
in the previous stage. Refer to the
326+
[component.get_detections_from_all_video_tracks(video_job)](Python-Batch-Component-API.md#componentget_detections_from_all_video_tracksvideo_job)
327+
section of the Python Batch Component API for more details. This property works in conjunction with the other
328+
feed-forward properties discussed in the [Feed Forward Properties](#feed-forward-properties) section.
329+
330+
Known limitations:
331+
332+
- Only Python supported.
333+
- Only video supported.
334+
- Not tested with [triggers](Trigger-Guide.md).

‎docs/docs/Python-Batch-Component-API.md‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -646,7 +646,7 @@ a static method, or a class method.
646646

647647

648648
#### mpf_component_api.VideoJob
649-
Class containing data used for detection of objects in a video file.
649+
Class containing data used for detection of objects in a video file. Contains at most one feed-forward track.
650650

651651
* Members:
652652

@@ -713,7 +713,7 @@ Class containing data used for detection of objects in a video file.
713713
<tr>
714714
<td>feed_forward_track</td>
715715
<td><code>None</code> or <code>mpf_component_api.VideoTrack</code></td>
716-
<td>An <code>mpf_component_api.VideoTrack</code> from the previous pipeline stage. Provided when feed forward is enabled. See <a href="../Feed-Forward-Guide/index.html">Feed Forward Guide</a>.</td>
716+
<td>An optional <code>mpf_component_api.VideoTrack</code> from the previous pipeline stage. Provided when feed forward is enabled. See <a href="../Feed-Forward-Guide/index.html">Feed Forward Guide</a>.</td>
717717
</tr>
718718
</tbody>
719719
</table>
@@ -733,6 +733,65 @@ they should only be used to specify properties that will not change throughout t
733733
of the service (e.g. Docker container).
734734

735735

736+
#### component.get_detections_from_all_video_tracks(video_job)
737+
738+
<div style="background-color:DeepSkyBlue"><p style="color:white; padding:5px"><b>EXPERIMENTAL:</b> This feature is not fully implemented.</p></div>
739+
740+
Similar to `component.get_detections_from_video(video_job)`, but able to process multiple feed-forward tracks at once.
741+
Refer to the [Feed Forward All Tracks](Feed-Forward-Guide.md#feed-forward-all-tracks) section of the Feed Forward Guide
742+
to learn about the `FEED_FORWARD_ALL_TRACKS` property and how it affects feed-forward behavior.
743+
744+
Known limitation: No multi-track `mpf_component_util.VideoCapture` support.
745+
746+
* Method Definition:
747+
```python
748+
class MyComponent:
749+
def get_detections_from_all_video_tracks(self, video_job):
750+
return [mpf_component_api.VideoTrack(...), ...]
751+
```
752+
753+
`get_detections_from_all_video_tracks`, like all get_detections_from_\* methods, can be implemented either as an
754+
instance method, a static method, or a class method.
755+
756+
* Parameters:
757+
758+
| Parameter | Data Type | Description |
759+
|-----------|---------------------------------------|-------------|
760+
| video_job | `mpf_component_api.AllVideoTracksJob` | Object containing details about the work to be performed.
761+
762+
* Returns: An iterable of `mpf_component_api.VideoTrack`
763+
764+
765+
#### mpf_component_api.AllVideoTracksJob
766+
767+
<div style="background-color:DeepSkyBlue"><p style="color:white; padding:5px"><b>EXPERIMENTAL:</b> This feature is not fully implemented.</p></div>
768+
769+
Class containing data used for detection of objects in a video file. May contain multiple feed-forward tracks.
770+
771+
Members are the same as `mpf_component_api.VideoJob` with the exception that `feed_forward_track` is replaced by
772+
`feed_forward_tracks`.
773+
774+
* Members:
775+
776+
<table>
777+
<thead>
778+
<tr>
779+
<th>Member</th>
780+
<th>Data Type</th>
781+
<th>Description</th>
782+
</tr>
783+
</thead>
784+
<tbody>
785+
<tr>
786+
<td>feed_forward_tracks</td>
787+
<td><code>None</code> or <code>List[mpf_component_api.VideoTrack]</code></td>
788+
<td>An optional list of <code>mpf_component_api.VideoTrack</code> objects from the previous pipeline stage. Provided when feed forward is enabled and <code>FEED_FORWARD_ALL_TRACKS</code> is true. See <a href="../Feed-Forward-Guide/index.html#feed-forward-all-tracks">Feed Forward Guide</a>.</td>
789+
</tr>
790+
</tbody>
791+
</table>
792+
793+
794+
736795
#### mpf_component_api.VideoTrack
737796
Class used to store the location of detected objects in a video file.
738797

‎docs/site/Feed-Forward-Guide/index.html‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,9 @@
124124
<li class="toctree-l3"><a href="#feed-forward-pipeline-examples">Feed Forward Pipeline Examples</a></li>
125125

126126

127+
<li class="toctree-l3"><a href="#feed-forward-all-tracks">Feed Forward All Tracks</a></li>
128+
129+
127130
</ul>
128131
</li>
129132
<li class="">
@@ -523,6 +526,24 @@ <h1 id="feed-forward-pipeline-examples">Feed Forward Pipeline Examples</h1>
523526
<p>Refer to <code>runMogThenOcvFaceFeedForwardRegionTest()</code> in the
524527
<a href="https://github.com/openmpf/openmpf/blob/master/trunk/mpf-system-tests/src/test/java/org/mitre/mpf/mst/TestSystemOnDiff.java"><code>TestSystemOnDiff</code></a>
525528
class for a system test that demonstrates this behavior.</p>
529+
<h1 id="feed-forward-all-tracks">Feed Forward All Tracks</h1>
530+
<div style="background-color:DeepSkyBlue"><p style="color:white; padding:5px"><b>EXPERIMENTAL:</b> This feature is not fully implemented.</p></div>
531+
532+
<p>The default feed-forward behavior will result in generating one sub-job per track generated in the previous stage.
533+
Consider a scenario where you need to implement a tracking component that takes individual detections from a stage and
534+
groups them into tracks. That component needs to accept all tracks from the previous stage as an input to the same
535+
sub-job.</p>
536+
<p>Setting <code>FEED_FORWARD_ALL_TRACKS</code> to true will result in generating one sub-job that contains all the tracks generated
537+
in the previous stage. Refer to the
538+
<a href="../Python-Batch-Component-API/index.html#componentget_detections_from_all_video_tracksvideo_job">component.get_detections_from_all_video_tracks(video_job)</a>
539+
section of the Python Batch Component API for more details. This property works in conjunction with the other
540+
feed-forward properties discussed in the <a href="#feed-forward-properties">Feed Forward Properties</a> section.</p>
541+
<p>Known limitations:</p>
542+
<ul>
543+
<li>Only Python supported.</li>
544+
<li>Only video supported.</li>
545+
<li>Not tested with <a href="../Trigger-Guide/index.html">triggers</a>.</li>
546+
</ul>
526547

527548
</div>
528549
</div>

‎docs/site/Python-Batch-Component-API/index.html‎

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -881,7 +881,7 @@ <h4 id="componentget_detections_from_videovideo_job">component.get_detections_fr
881881
<li>Returns: An iterable of <code>mpf_component_api.VideoTrack</code></li>
882882
</ul>
883883
<h4 id="mpf_component_apivideojob">mpf_component_api.VideoJob</h4>
884-
<p>Class containing data used for detection of objects in a video file.</p>
884+
<p>Class containing data used for detection of objects in a video file. Contains at most one feed-forward track.</p>
885885
<ul>
886886
<li>Members:</li>
887887
</ul>
@@ -948,7 +948,7 @@ <h4 id="mpf_component_apivideojob">mpf_component_api.VideoJob</h4>
948948
<tr>
949949
<td>feed_forward_track</td>
950950
<td><code>None</code> or <code>mpf_component_api.VideoTrack</code></td>
951-
<td>An <code>mpf_component_api.VideoTrack</code> from the previous pipeline stage. Provided when feed forward is enabled. See <a href="../Feed-Forward-Guide/index.html">Feed Forward Guide</a>.</td>
951+
<td>An optional <code>mpf_component_api.VideoTrack</code> from the previous pipeline stage. Provided when feed forward is enabled. See <a href="../Feed-Forward-Guide/index.html">Feed Forward Guide</a>.</td>
952952
</tr>
953953
</tbody>
954954
</table>
@@ -967,6 +967,70 @@ <h4 id="mpf_component_apivideojob">mpf_component_api.VideoJob</h4>
967967
possible to change the value of properties set via environment variables at runtime and therefore
968968
they should only be used to specify properties that will not change throughout the entire lifetime
969969
of the service (e.g. Docker container).</p>
970+
<h4 id="componentget_detections_from_all_video_tracksvideo_job">component.get_detections_from_all_video_tracks(video_job)</h4>
971+
<div style="background-color:DeepSkyBlue"><p style="color:white; padding:5px"><b>EXPERIMENTAL:</b> This feature is not fully implemented.</p></div>
972+
973+
<p>Similar to <code>component.get_detections_from_video(video_job)</code>, but able to process multiple feed-forward tracks at once.
974+
Refer to the <a href="../Feed-Forward-Guide/index.html#feed-forward-all-tracks">Feed Forward All Tracks</a> section of the Feed Forward Guide
975+
to learn about the <code>FEED_FORWARD_ALL_TRACKS</code> property and how it affects feed-forward behavior.</p>
976+
<p>Known limitation: No multi-track <code>mpf_component_util.VideoCapture</code> support.</p>
977+
<ul>
978+
<li>Method Definition:</li>
979+
</ul>
980+
<pre><code class="language-python">class MyComponent:
981+
def get_detections_from_all_video_tracks(self, video_job):
982+
return [mpf_component_api.VideoTrack(...), ...]
983+
</code></pre>
984+
<p><code>get_detections_from_all_video_tracks</code>, like all get_detections_from_* methods, can be implemented either as an
985+
instance method, a static method, or a class method.</p>
986+
<ul>
987+
<li>Parameters:</li>
988+
</ul>
989+
<table>
990+
<thead>
991+
<tr>
992+
<th>Parameter</th>
993+
<th>Data Type</th>
994+
<th>Description</th>
995+
</tr>
996+
</thead>
997+
<tbody>
998+
<tr>
999+
<td>video_job</td>
1000+
<td><code>mpf_component_api.AllVideoTracksJob</code></td>
1001+
<td>Object containing details about the work to be performed.</td>
1002+
</tr>
1003+
</tbody>
1004+
</table>
1005+
<ul>
1006+
<li>Returns: An iterable of <code>mpf_component_api.VideoTrack</code></li>
1007+
</ul>
1008+
<h4 id="mpf_component_apiallvideotracksjob">mpf_component_api.AllVideoTracksJob</h4>
1009+
<div style="background-color:DeepSkyBlue"><p style="color:white; padding:5px"><b>EXPERIMENTAL:</b> This feature is not fully implemented.</p></div>
1010+
1011+
<p>Class containing data used for detection of objects in a video file. May contain multiple feed-forward tracks.</p>
1012+
<p>Members are the same as <code>mpf_component_api.VideoJob</code> with the exception that <code>feed_forward_track</code> is replaced by
1013+
<code>feed_forward_tracks</code>.</p>
1014+
<ul>
1015+
<li>Members:</li>
1016+
</ul>
1017+
<table>
1018+
<thead>
1019+
<tr>
1020+
<th>Member</th>
1021+
<th>Data Type</th>
1022+
<th>Description</th>
1023+
</tr>
1024+
</thead>
1025+
<tbody>
1026+
<tr>
1027+
<td>feed_forward_tracks</td>
1028+
<td><code>None</code> or <code>List[mpf_component_api.VideoTrack]</code></td>
1029+
<td>An optional list of <code>mpf_component_api.VideoTrack</code> objects from the previous pipeline stage. Provided when feed forward is enabled and <code>FEED_FORWARD_ALL_TRACKS</code> is true. See <a href="../Feed-Forward-Guide/index.html#feed-forward-all-tracks">Feed Forward Guide</a>.</td>
1030+
</tr>
1031+
</tbody>
1032+
</table>
1033+
9701034
<h4 id="mpf_component_apivideotrack">mpf_component_api.VideoTrack</h4>
9711035
<p>Class used to store the location of detected objects in a video file.</p>
9721036
<ul>

‎docs/site/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -408,5 +408,5 @@ <h1 id="overview">Overview</h1>
408408

409409
<!--
410410
MkDocs version : 0.17.5
411-
Build Date UTC : 2025-09-10 17:55:24
411+
Build Date UTC : 2025-09-19 21:32:58
412412
-->

‎docs/site/search/search_index.json‎

Lines changed: 18 additions & 3 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)