Skip to content

Commit 7032584

Browse files
jrobblejrobble
authored
Update API docs with NETWORK_ERROR, COULD_NOT_OPEN_MEDIA, and COULD_NOT_READ_MEDIA error codes. (#129)
1 parent 88ffe25 commit 7032584

11 files changed

Lines changed: 121 additions & 53 deletions

File tree

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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The Component Executable:
2323
2. Invokes functions on the component library to obtain detection results
2424
3. Populates and sends the respective responses to the WFM
2525

26-
The basic psuedocode for the Component Executable is as follows:
26+
The basic pseudocode for the Component Executable is as follows:
2727

2828
```c++
2929
component->SetRunDirectory(...)
@@ -1003,10 +1003,10 @@ the `MPFDetectionException` constructor. A component is not required to support
10031003
| MPF_UNRECOGNIZED_DATA_TYPE | The media data type received by a component is not one of the values contained in the MPFDetectionDataType enum. Note that this failure is normally caught by the Component Executable, before a job is passed to the component logic. |
10041004
| MPF_UNSUPPORTED_DATA_TYPE | The job passed to a component requests processing of a job of an unsupported type. For instance, a component that is only capable of processing audio files should return this error code if a video or image job request is received. |
10051005
| MPF_INVALID_DATAFILE_URI | The string containing the URI location of the input data file is invalid or empty. |
1006-
| MPF_COULD_NOT_OPEN_DATAFILE | The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. |
1007-
| MPF_COULD_NOT_READ_DATAFILE | There is a failure reading data from a successfully opened input data file. |
1006+
| MPF_COULD_NOT_OPEN_DATAFILE | The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. <br><br>Use MPF_COULD_NOT_OPEN_MEDIA for media files. |
1007+
| MPF_COULD_NOT_READ_DATAFILE | There is a failure reading data from a successfully opened input data file. <br><br>Use MPF_COULD_NOT_READ_MEDIA for media files. |
10081008
| MPF_FILE_WRITE_ERROR | The component received a failure for any reason when attempting to write to a file. |
1009-
| MPF_IMAGE_READ_ERROR | The component failed to read the image provided by the URI. For example, it might indicate the failure of a call to `MPFImageReader::GetImage()`, or `cv::imread()`. |
1009+
| MPF_IMAGE_READ_ERROR | Use MPF_COULD_NOT_READ_MEDIA instead. This error is only kept for backwards compatibility and may be removed in a future release. <br><br>*The component failed to read the image provided by the URI. For example, it might indicate the failure of a call to `MPFImageReader::GetImage()`, or `cv::imread()`.* |
10101010
| MPF_BAD_FRAME_SIZE | The frame data retrieved has an incorrect or invalid frame size. For example, if a call to `cv::imread()` returns a frame of data with either the number of rows or columns less than or equal to 0. |
10111011
| MPF_BOUNDING_BOX_SIZE_ERROR | The calculation of a detection location bounding box has failed. For example, a component may be using an external library to detect objects, but the bounding box returned by that library lies partially outside the frame boundaries. |
10121012
| MPF_INVALID_FRAME_INTERVAL | An invalid or unsupported frame interval was received. |
@@ -1020,6 +1020,9 @@ the `MPFDetectionException` constructor. A component is not required to support
10201020
| MPF_JOB_PROPERTY_IS_NOT_FLOAT | A job property is supposed to be a floating point type, but it is of some other type, such as a boolean value. |
10211021
| MPF_MEMORY_ALLOCATION_FAILED | The component failed to allocate memory for any reason. |
10221022
| MPF_GPU_ERROR | The job was configured to execute on a GPU, but there was an issue with the GPU or no GPU was detected. |
1023+
| MPF_NETWORK_ERROR | The component failed to communicate with an external system over the network. The system may not be available or there may have been a timeout. |
1024+
| MPF_COULD_NOT_OPEN_MEDIA | The media file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. |
1025+
| MPF_COULD_NOT_READ_MEDIA | There is a failure reading data from a successfully opened media file. |
10231026
10241027
### Utility Classes
10251028

‎docs/docs/CPP-Streaming-Component-API.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ The Component Executable:
2424
2. Invokes functions on the component library to obtain detection results
2525
3. Populates and sends the respective responses to the WFM
2626

27-
The basic psuedocode for the Component Executable is as follows:
27+
The basic pseudocode for the Component Executable is as follows:
2828

2929
```c++
3030
while (has_next_frame) {

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

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The Component Executor:
2323
2. Invokes methods on the component library to obtain detection results
2424
3. Populates and sends the respective responses to the WFM
2525

26-
The basic psuedocode for the Component Executor is as follows:
26+
The basic pseudocode for the Component Executor is as follows:
2727
```java
2828
component.setRunDirectory(...)
2929
component.init()
@@ -917,10 +917,10 @@ Enum used to indicate the status of `getDetections` in a [`MPFComponentDetection
917917
| MPF_UNRECOGNIZED_DATA_TYPE | The media data type received by a component is not one of the values contained in the `MPFDataType` enum. Note that this failure is normally caught by the Component Executor before a job is passed to the component logic. |
918918
| MPF_UNSUPPORTED_DATA_TYPE | The job passed to a component requests processing of a job of an unsupported type. For instance, a component that is only capable of processing audio files should return this error code if a video or image job request is received. |
919919
| MPF_INVALID_DATAFILE_URI | The string containing the URI location of the input data file is invalid or empty. |
920-
| MPF_COULD_NOT_OPEN_DATAFILE | The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. |
921-
| MPF_COULD_NOT_READ_DATAFILE | There is a failure reading data from a successfully opened input data file. |
920+
| MPF_COULD_NOT_OPEN_DATAFILE | The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. <br><br>Use MPF_COULD_NOT_OPEN_MEDIA for media files. |
921+
| MPF_COULD_NOT_READ_DATAFILE | There is a failure reading data from a successfully opened input data file. <br><br>Use MPF_COULD_NOT_READ_MEDIA for media files. |
922922
| MPF_FILE_WRITE_ERROR | The component received a failure for any reason when attempting to write to a file. |
923-
| MPF_IMAGE_READ_ERROR | The component failed to read the image provided by the URI. |
923+
| MPF_IMAGE_READ_ERROR | Use MPF_COULD_NOT_READ_MEDIA instead. This error is only kept for backwards compatibility and may be removed in a future release. <br><br>*The component failed to read the image provided by the URI.* |
924924
| MPF_BAD_FRAME_SIZE | The frame data retrieved has an incorrect or invalid frame size. |
925925
| MPF_BOUNDING_BOX_SIZE_ERROR | The calculation of a detection location bounding box has failed. For example, a component may be using an external library to detect objects, but the bounding box returned by that library lies partially outside the frame boundaries. |
926926
| MPF_INVALID_FRAME_INTERVAL | An invalid or unsupported frame interval was received. |
@@ -935,6 +935,9 @@ Enum used to indicate the status of `getDetections` in a [`MPFComponentDetection
935935
| MPF_INVALID_ROTATION | The component received a job that requests rotation of the media, but the rotation value given is not in the set of acceptable values. The set of acceptable values is {0, 90, 180, 270}. |
936936
| MPF_MEMORY_ALLOCATION_FAILED | The component failed to allocate memory for any reason. |
937937
| MPF_GPU_ERROR | The job was configured to execute on a GPU, but there was an issue with the GPU or no GPU was detected. |
938+
| MPF_NETWORK_ERROR | The component failed to communicate with an external system over the network. The system may not be available or there may have been a timeout. |
939+
| MPF_COULD_NOT_OPEN_MEDIA | The media file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. |
940+
| MPF_COULD_NOT_READ_MEDIA | There is a failure reading data from a successfully opened media file. |
938941

939942
### Utility Classes
940943

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

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ The Component Executable:
2929
2. Invokes methods on the component library to obtain detection results
3030
3. Populates and sends the respective responses to the WFM
3131

32-
The basic psuedocode for the Component Executable is as follows:
32+
The basic pseudocode for the Component Executable is as follows:
3333
```python
3434
component_cls = locate_component_class()
3535
component = component_cls()
@@ -1072,6 +1072,23 @@ def __init__(self, confidence=-1.0, detection_properties=None):
10721072
| detection_properties | `dict[str, str]` | A dict with keys and values of type `str` containing optional additional information about the detected object. For best practice, keys should be in all CAPS. |
10731073

10741074

1075+
# How to Report Errors
1076+
The following is an example of how to throw an exception:
1077+
1078+
```python
1079+
import mpf_component_api as mpf
1080+
1081+
...
1082+
raise mpf.DetectionError.MISSING_PROPERTY.exception(
1083+
'The REALLY_IMPORTANT property must be provided as a job property.')
1084+
```
1085+
1086+
The Python Batch Component API supports all of the same error types
1087+
listed [here](/CPP-Batch-Component-API/index.html#mpfdetectionerror) for the C++ Batch Component API. Be sure to omit
1088+
the `MPF_` prefix. You can replace the `MISSING_PROPERTY` part in the above code with any other error type. When
1089+
generating an exception, choose the type that best describes your error.
1090+
1091+
10751092
# Python Component Build Environment
10761093
All Python components must work with CPython 3.8.2. Also, Python components must work with the Linux version that is
10771094
used by the OpenMPF Component Executable. At this writing, OpenMPF runs on CentOS 7.4.1708 (kernel version 3.10.0-693).

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

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -315,7 +315,7 @@ <h2 id="how-components-integrate-into-openmpf">How Components Integrate into Ope
315315
<li>Invokes functions on the component library to obtain detection results</li>
316316
<li>Populates and sends the respective responses to the WFM</li>
317317
</ol>
318-
<p>The basic psuedocode for the Component Executable is as follows:</p>
318+
<p>The basic pseudocode for the Component Executable is as follows:</p>
319319
<pre><code class="c++">component-&gt;SetRunDirectory(...)
320320
component-&gt;Init()
321321
while (true) {
@@ -1489,19 +1489,19 @@ <h4 id="mpfdetectionerror">MPFDetectionError</h4>
14891489
</tr>
14901490
<tr>
14911491
<td>MPF_COULD_NOT_OPEN_DATAFILE</td>
1492-
<td>The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI.</td>
1492+
<td>The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. <br><br>Use MPF_COULD_NOT_OPEN_MEDIA for media files.</td>
14931493
</tr>
14941494
<tr>
14951495
<td>MPF_COULD_NOT_READ_DATAFILE</td>
1496-
<td>There is a failure reading data from a successfully opened input data file.</td>
1496+
<td>There is a failure reading data from a successfully opened input data file. <br><br>Use MPF_COULD_NOT_READ_MEDIA for media files.</td>
14971497
</tr>
14981498
<tr>
14991499
<td>MPF_FILE_WRITE_ERROR</td>
15001500
<td>The component received a failure for any reason when attempting to write to a file.</td>
15011501
</tr>
15021502
<tr>
15031503
<td>MPF_IMAGE_READ_ERROR</td>
1504-
<td>The component failed to read the image provided by the URI. For example, it might indicate the failure of a call to <code>MPFImageReader::GetImage()</code>, or <code>cv::imread()</code>.</td>
1504+
<td>Use MPF_COULD_NOT_READ_MEDIA instead. This error is only kept for backwards compatibility and may be removed in a future release. <br><br><em>The component failed to read the image provided by the URI. For example, it might indicate the failure of a call to <code>MPFImageReader::GetImage()</code>, or <code>cv::imread()</code>.</em></td>
15051505
</tr>
15061506
<tr>
15071507
<td>MPF_BAD_FRAME_SIZE</td>
@@ -1555,6 +1555,18 @@ <h4 id="mpfdetectionerror">MPFDetectionError</h4>
15551555
<td>MPF_GPU_ERROR</td>
15561556
<td>The job was configured to execute on a GPU, but there was an issue with the GPU or no GPU was detected.</td>
15571557
</tr>
1558+
<tr>
1559+
<td>MPF_NETWORK_ERROR</td>
1560+
<td>The component failed to communicate with an external system over the network. The system may not be available or there may have been a timeout.</td>
1561+
</tr>
1562+
<tr>
1563+
<td>MPF_COULD_NOT_OPEN_MEDIA</td>
1564+
<td>The media file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI.</td>
1565+
</tr>
1566+
<tr>
1567+
<td>MPF_COULD_NOT_READ_MEDIA</td>
1568+
<td>There is a failure reading data from a successfully opened media file.</td>
1569+
</tr>
15581570
</tbody>
15591571
</table>
15601572
<h3 id="utility-classes">Utility Classes</h3>

‎docs/site/CPP-Streaming-Component-API/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,7 +321,7 @@ <h2 id="how-components-integrate-into-openmpf">How Components Integrate into Ope
321321
<li>Invokes functions on the component library to obtain detection results</li>
322322
<li>Populates and sends the respective responses to the WFM</li>
323323
</ol>
324-
<p>The basic psuedocode for the Component Executable is as follows:</p>
324+
<p>The basic pseudocode for the Component Executable is as follows:</p>
325325
<pre><code class="c++">while (has_next_frame) {
326326
if (is_new_segment) {
327327
component-&gt;BeginSegment(video_segment_info)

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

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ <h2 id="how-components-integrate-into-openmpf">How Components Integrate into Ope
313313
<li>Invokes methods on the component library to obtain detection results</li>
314314
<li>Populates and sends the respective responses to the WFM</li>
315315
</ol>
316-
<p>The basic psuedocode for the Component Executor is as follows:</p>
316+
<p>The basic pseudocode for the Component Executor is as follows:</p>
317317
<pre><code class="java">component.setRunDirectory(...)
318318
component.init()
319319
while (true) {
@@ -1449,19 +1449,19 @@ <h4 id="mpfdetectionerror">MPFDetectionError</h4>
14491449
</tr>
14501450
<tr>
14511451
<td>MPF_COULD_NOT_OPEN_DATAFILE</td>
1452-
<td>The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI.</td>
1452+
<td>The data file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI. <br><br>Use MPF_COULD_NOT_OPEN_MEDIA for media files.</td>
14531453
</tr>
14541454
<tr>
14551455
<td>MPF_COULD_NOT_READ_DATAFILE</td>
1456-
<td>There is a failure reading data from a successfully opened input data file.</td>
1456+
<td>There is a failure reading data from a successfully opened input data file. <br><br>Use MPF_COULD_NOT_READ_MEDIA for media files.</td>
14571457
</tr>
14581458
<tr>
14591459
<td>MPF_FILE_WRITE_ERROR</td>
14601460
<td>The component received a failure for any reason when attempting to write to a file.</td>
14611461
</tr>
14621462
<tr>
14631463
<td>MPF_IMAGE_READ_ERROR</td>
1464-
<td>The component failed to read the image provided by the URI.</td>
1464+
<td>Use MPF_COULD_NOT_READ_MEDIA instead. This error is only kept for backwards compatibility and may be removed in a future release. <br><br><em>The component failed to read the image provided by the URI.</em></td>
14651465
</tr>
14661466
<tr>
14671467
<td>MPF_BAD_FRAME_SIZE</td>
@@ -1519,6 +1519,18 @@ <h4 id="mpfdetectionerror">MPFDetectionError</h4>
15191519
<td>MPF_GPU_ERROR</td>
15201520
<td>The job was configured to execute on a GPU, but there was an issue with the GPU or no GPU was detected.</td>
15211521
</tr>
1522+
<tr>
1523+
<td>MPF_NETWORK_ERROR</td>
1524+
<td>The component failed to communicate with an external system over the network. The system may not be available or there may have been a timeout.</td>
1525+
</tr>
1526+
<tr>
1527+
<td>MPF_COULD_NOT_OPEN_MEDIA</td>
1528+
<td>The media file to be processed could not be opened for any reason, such as a permissions failure, or an unreachable URI.</td>
1529+
</tr>
1530+
<tr>
1531+
<td>MPF_COULD_NOT_READ_MEDIA</td>
1532+
<td>There is a failure reading data from a successfully opened media file.</td>
1533+
</tr>
15221534
</tbody>
15231535
</table>
15241536
<h3 id="utility-classes">Utility Classes</h3>

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,9 @@
208208
<li><a class="toctree-l4" href="#generic-api">Generic API</a></li>
209209

210210

211+
<li class="toctree-l3"><a href="#how-to-report-errors">How to Report Errors</a></li>
212+
213+
211214
<li class="toctree-l3"><a href="#python-component-build-environment">Python Component Build Environment</a></li>
212215

213216

@@ -334,7 +337,7 @@ <h2 id="how-components-integrate-into-openmpf">How Components Integrate into Ope
334337
<li>Invokes methods on the component library to obtain detection results</li>
335338
<li>Populates and sends the respective responses to the WFM</li>
336339
</ol>
337-
<p>The basic psuedocode for the Component Executable is as follows:</p>
340+
<p>The basic pseudocode for the Component Executable is as follows:</p>
338341
<pre><code class="python">component_cls = locate_component_class()
339342
component = component_cls()
340343
detection_type = component.detection_type
@@ -1416,6 +1419,19 @@ <h4 id="mpf_component_apigenerictrack">mpf_component_api.GenericTrack</h4>
14161419
</tr>
14171420
</tbody>
14181421
</table>
1422+
<h1 id="how-to-report-errors">How to Report Errors</h1>
1423+
<p>The following is an example of how to throw an exception:</p>
1424+
<pre><code class="python">import mpf_component_api as mpf
1425+
1426+
...
1427+
raise mpf.DetectionError.MISSING_PROPERTY.exception(
1428+
'The REALLY_IMPORTANT property must be provided as a job property.')
1429+
</code></pre>
1430+
1431+
<p>The Python Batch Component API supports all of the same error types
1432+
listed <a href="../CPP-Batch-Component-API/index.html#mpfdetectionerror">here</a> for the C++ Batch Component API. Be sure to omit
1433+
the <code>MPF_</code> prefix. You can replace the <code>MISSING_PROPERTY</code> part in the above code with any other error type. When
1434+
generating an exception, choose the type that best describes your error.</p>
14191435
<h1 id="python-component-build-environment">Python Component Build Environment</h1>
14201436
<p>All Python components must work with CPython 3.8.2. Also, Python components must work with the Linux version that is
14211437
used by the OpenMPF Component Executable. At this writing, OpenMPF runs on CentOS 7.4.1708 (kernel version 3.10.0-693).

‎docs/site/index.html‎

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

438438
<!--
439439
MkDocs version : 0.16.0
440-
Build Date UTC : 2021-05-13 17:40:17
440+
Build Date UTC : 2021-05-20 14:34:13
441441
-->

‎docs/site/mkdocs/search_index.json‎

Lines changed: 15 additions & 10 deletions
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)