New Artifact Extraction Guide

[clnowacki]

Issues:

• Add an artifact extraction guide to the github.io documentation openmpf#1871

---

This change is 

[jrobble]

Reviewed 45 of 45 files at r1, all commit messages.
Reviewable status: all files reviewed, 12 unresolved discussions (waiting on @clnowacki)

---

docs/docs/Artifact-Extraction-Guide.md line 32 at r1 (raw file):

The values of these properties are "or-ed" together

I know what you're going for, but this would be confusing to a non-developer. Say something to the effect of:

These properties can be combined, for example, if ARTIFACT_EXTRACTION_POLICY_FIRST_FRAME=true and ARTIFACT_EXTRACTION_POLICY_MIDDLE_FRAME=true then the first and middle frames will always be extracted. If ARTIFACT_EXTRACTION_POLICY_CROPPING=true is also set then the detection crops for the first and middle frames will be extracted instead of the whole frames. If ARTIFACT_EXTRACTION_POLICY_TOP_QUALITY_COUNT=5 is also set then the above still applies but additional crops may be extracted until the top 5 is reached. Note that the top 5 may already include first and middle frames.

It's important to provide the examples for clarity.

---

docs/docs/Quality-Selection-Guide.md line 30 at r1 (raw file):

that. The allowed values for this property are:

- `FIRST`, which selects the first detection in each track as the exemplar

Use colons instead of commas after these for consistency with other docs.

---

docs/docs/Artifact-Extraction-Guide.md line 7 at r1 (raw file):

Artifact extraction is an optional behavior of OpenMPF that allows the user to save artifacts from a job onto disk. An
artifact is a frame extracted from a piece of media. Extracting artifacts gives you a way to visualize representative

Say "frame region extracted from a piece of media". The artifact can be a crop.

---

docs/docs/Artifact-Extraction-Guide.md line 9 at r1 (raw file):

artifact is a frame extracted from a piece of media. Extracting artifacts gives you a way to visualize representative
detections from the tracks found in a piece of media. For example, you might want to extract an artifact for the
exemplar in all tracks found in a piece of media, or you might want to extract artifacts for the exemplar and a few

This is the first time in this doc you mention exemplar. Define it and link to the Quality Selection Guide.

---

docs/docs/Artifact-Extraction-Guide.md line 10 at r1 (raw file):

detections from the tracks found in a piece of media. For example, you might want to extract an artifact for the
exemplar in all tracks found in a piece of media, or you might want to extract artifacts for the exemplar and a few
other frames that come before and after the exemplar. The workflow manager performs artifact extraction after all

Capitalize all instances of "workflow manager" to "Workflow Manager" in this doc for consistency with other docs.

---

docs/docs/Artifact-Extraction-Guide.md line 11 at r1 (raw file):

exemplar in all tracks found in a piece of media, or you might want to extract artifacts for the exemplar and a few
other frames that come before and after the exemplar. The workflow manager performs artifact extraction after all
detection processing for a job is complete. Artifacts can be written to local shared storage, or to a remote S3 storage

Link to Object Storage Guide.

---

docs/docs/Artifact-Extraction-Guide.md line 31 at r1 (raw file):

With the `VISUAL_TYPES_ONLY` or `ALL_TYPES` policy, artifacts will be extracted according to the
`ARTIFACT_EXTRACTION_POLICY_XXX` properties described below. With the `NONE` and `ALL_DETECTIONS` policies, these

Instead of ARTIFACT_EXTRACTION_POLICY_XXX, use ARTIFACT_EXTRACTION_POLICY_* to be consistent with other docs.

---

docs/docs/Artifact-Extraction-Guide.md line 34 at r1 (raw file):

properties are ignored. The values of these properties are "or-ed" together, but if a detection satisfies more than one property, it will only be extracted exactly once.

- `ARTIFACT_EXTRACTION_POLICY_CROPPING`: A boolean property which if set to true, causes the extracted artifact to

Let's avoid coder lingo like boolean. Just start with "If set to true, ...".

---

docs/docs/Artifact-Extraction-Guide.md line 55 at r1 (raw file):

- `ARTIFACT_EXTRACTION_POLICY_TOP_QUALITY_COUNT`: When this property is set to an integer value N greater than 0
the detections in a track will be sorted by the detection property given by the `QUALITY_SELECTION_PROPERTY` job

Link to the Quality Selection Guide here.

---

docs/docs/Artifact-Extraction-Guide.md line 67 at r1 (raw file):

# Artifact Cropping and Rotation

If the `ARTIFACT_EXTRACTION_POLICY_CROPPING` job property is set to true, then the bounding box in the detection object is used to define the cropping. Here is an example showing an image where two detections were found. The two detections in the frame are illustrated with the bounding boxes added by markup. The cropped artifacts are also shown below. Notice that the detection on the left in the image is rotated, but the cropped artifact has had the rotation removed.

Link to Markup Guide.

---

docs/docs/Artifact-Extraction-Guide.md line 69 at r1 (raw file):

If the `ARTIFACT_EXTRACTION_POLICY_CROPPING` job property is set to true, then the bounding box in the detection object is used to define the cropping. Here is an example showing an image where two detections were found. The two detections in the frame are illustrated with the bounding boxes added by markup. The cropped artifacts are also shown below. Notice that the detection on the left in the image is rotated, but the cropped artifact has had the rotation removed.

## Image with markup

Use capitalization: "Image with Markup".

---

docs/docs/Artifact-Extraction-Guide.md line 71 at r1 (raw file):

## Image with markup

![Image With Markup](img/artifacts/original_with_markup.png "Image With Markup")

Nice examples. Remind me, what's the license / usage of this image?

[clnowacki]

Reviewable status: 40 of 45 files reviewed, 12 unresolved discussions (waiting on @jrobble)

---

docs/docs/Artifact-Extraction-Guide.md line 7 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Say "frame region extracted from a piece of media". The artifact can be a crop.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 9 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

This is the first time in this doc you mention exemplar. Define it and link to the Quality Selection Guide.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 10 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Capitalize all instances of "workflow manager" to "Workflow Manager" in this doc for consistency with other docs.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 11 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Link to Object Storage Guide.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 31 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Instead of ARTIFACT_EXTRACTION_POLICY_XXX, use ARTIFACT_EXTRACTION_POLICY_* to be consistent with other docs.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 32 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

The values of these properties are "or-ed" together

I know what you're going for, but this would be confusing to a non-developer. Say something to the effect of:

These properties can be combined, for example, if ARTIFACT_EXTRACTION_POLICY_FIRST_FRAME=true and ARTIFACT_EXTRACTION_POLICY_MIDDLE_FRAME=true then the first and middle frames will always be extracted. If ARTIFACT_EXTRACTION_POLICY_CROPPING=true is also set then the detection crops for the first and middle frames will be extracted instead of the whole frames. If ARTIFACT_EXTRACTION_POLICY_TOP_QUALITY_COUNT=5 is also set then the above still applies but additional crops may be extracted until the top 5 is reached. Note that the top 5 may already include first and middle frames.

It's important to provide the examples for clarity.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 34 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Let's avoid coder lingo like boolean. Just start with "If set to true, ...".

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 55 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Link to the Quality Selection Guide here.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 67 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Link to Markup Guide.

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 69 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Use capitalization: "Image with Markup".

Done.

---

docs/docs/Artifact-Extraction-Guide.md line 71 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Nice examples. Remind me, what's the license / usage of this image?

It came from Pixabay. Here is a link to their license summary. Content License - Pixabay

---

docs/docs/Quality-Selection-Guide.md line 30 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Use colons instead of commas after these for consistency with other docs.

Done.

[jrobble]

Reviewed 7 of 7 files at r2, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @clnowacki)

---

docs/docs/Artifact-Extraction-Guide.md line 71 at r1 (raw file):

Previously, clnowacki wrote…

It came from Pixabay. Here is a link to their license summary. Content License - Pixabay

Ok. Add a NOTICE file like this one to /docs/docs/img/artifacts. Include entries for the three images in there. You can mention that they are all modifications of the original.

[clnowacki]

Reviewable status: 43 of 47 files reviewed, 1 unresolved discussion (waiting on @clnowacki and @jrobble)

---

docs/docs/Artifact-Extraction-Guide.md line 71 at r1 (raw file):

Previously, jrobble (Jeff Robble) wrote…

Ok. Add a NOTICE file like this one to /docs/docs/img/artifacts. Include entries for the three images in there. You can mention that they are all modifications of the original.

Done.

[jrobble]

Reviewed 4 of 4 files at r3, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @clnowacki)

---

docs/docs/img/artifacts/NOTICE line 2 at r3 (raw file):

# original_with_markup.png
Based on https://pixabay.com/photos/girls-students-asian-glasses-1741925/, which is public domain.

I went to this website. The content license is here: https://pixabay.com/service/license-summary/

There are restrictions on usage in the "What are you not allowed to do with Content?" section. Since there are restrictions, this is not a public domain image. That would mean no usage restrictions.

Please link to the Pixabay Content License and remove mention of public domain.

[clnowacki]

Reviewable status: 43 of 47 files reviewed, 1 unresolved discussion (waiting on @jrobble)

---

docs/docs/img/artifacts/NOTICE line 2 at r3 (raw file):

Previously, jrobble (Jeff Robble) wrote…

I went to this website. The content license is here: https://pixabay.com/service/license-summary/

There are restrictions on usage in the "What are you not allowed to do with Content?" section. Since there are restrictions, this is not a public domain image. That would mean no usage restrictions.

Please link to the Pixabay Content License and remove mention of public domain.

Done.

[jrobble]

Reviewed 4 of 4 files at r4, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @clnowacki)