# PRD — object_detection_py

Evidence date: 2026-10-08. Source: `git@bitbucket.org:overdrive/object_detection_py.git`, `main` at `b53f138` (2024-03-26, "update readme").

There is no prior PRD in Silicon Ark and no requirements document in the source repository. The only product text is `readme.md`. Requirements below are the operator steps that file records. Provenance is marked on each item.

This repository does not contain the scripts, weights, images, or label files those steps name. A tester cannot run the pipeline from a clone of `main` alone.

## Product purpose

Give a developer a local TensorFlow 2 object-detection workflow: prepare an environment, run a pretrained COCO detector on images, label images with LabelImg, convert Pascal VOC XML to CSV, and keep notes for a later TFRecord and EfficientDet training run.

Provenance: **Inferred** from the command sequence in `readme.md`. The file never states a product goal, a customer, or a domain (what kind of object). The command sequence itself is **Documented**.

## Users and roles

| Role | What they do | Evidence | Provenance |
|---|---|---|---|
| Developer on a workstation | Creates a conda env, installs packages, runs the Python commands in the readme | `readme.md` | Documented as commands. The reader is not named |
| Dirk | Wrote and corrected the readme; added the `tf2/models` gitlink | commits `c496ae6`, `0d91c62`, `b53f138` | Implemented in git history |
| Jaco Brits | Created the repository and the `.gitignore` | commit `3eaa9eb` | Implemented in git history |

No end-user account, role, or permission model exists in the repository. Whether anyone other than Dirk was meant to follow the notes is **Unknown / Requires Confirmation**.

Windows is suggested by `.\` paths and `labelimg.exe`. Provenance: **Inferred** from `readme.md`. Conda itself is cross-platform.

## Main workflows

### W1 — Prepare the environment

The readme tells the reader to:

1. `conda install python=3.9` (written as its own bullet, before the env exists).
2. `conda create -n {name} python=3.9`.
3. `conda activate {name}`.
4. `python use_protobuff.py object_detection/protos protoc`.
5. `python -m pip install .`
6. `conda install numpy`
7. `cd research/object_detection`

`{name}` is a placeholder, not a concrete environment name.

Provenance: **Documented**. `use_protobuff.py` is not in this repo and was not found at `research/object_detection/use_protobuff.py` on the pinned `tensorflow/models` commit. The `pip install .` line is written before the `cd`, so the package directory is ambiguous. Provenance of that ambiguity: **Documented** by the order of the lines.

### W2 — Check the Object Detection install

```text
python builders/model_builder_tf2_test.py
```

The readme places this under `*** test` after the `cd research/object_detection` line.

Provenance: **Documented** command. `builders/model_builder_tf2_test.py` exists in `tensorflow/models` at `505c718` under `research/object_detection/builders/`. It is not a blob in `object_detection_py`. This repo has no test runner, no CI config, and no record of the test result.

### W3 — Detect objects in images

```text
pip install wget

python .\detect_from_image.py -m ssd_mobilenet_v2_320x320_coco17_tpu-8\saved_model -l .\data\mscoco_label_map.pbtxt -i .\images
```

Provenance: **Documented** command.

| Input the command names | In this git tree | On `tensorflow/models` @ `505c718` under `research/object_detection/` |
|---|---|---|
| `detect_from_image.py` | No | No (HTTP 404 on 2026-10-08) |
| `ssd_mobilenet_v2_320x320_coco17_tpu-8\saved_model` | No | Not part of the models repository; it is a checkpoint name |
| `.\data\mscoco_label_map.pbtxt` | No | Yes, `data/mscoco_label_map.pbtxt` |
| `.\images` | No | No image set in this repo |

What `wget` is for is **Unknown**. The readme never shows a download URL.

The model name is the public TensorFlow 2 Detection Model Zoo id for SSD MobileNet V2 at 320×320, trained on COCO 2017. That identification is **Inferred** from the directory string. The readme does not say COCO in prose.

### W4 — Label images and convert XML to CSV

```text
pip install labelimg
run -> labelimg.exe
python xml_to_csv.py
```

Provenance: **Documented**. `xml_to_csv.py` is not in this repo and was not at `research/object_detection/xml_to_csv.py` on the pinned commit. LabelImg is a third-party package named by the install command. No label schema, class list, or output CSV path is written down.

### W5 — Build TFRecords and train (commented)

Both of these lines are comments in `readme.md`:

```text
# python generate_tfrecord.py --csv_input=images/test_labels.csv --image_dir=images/test --output_path=test.record
# python generate_tfrecord.py --csv_input=images/train_labels.csv --image_dir=images/train --output_path=train.record

# python model_main_tf2.py --pipeline_config_path=ssd_efficientdet_d0_512x512_coco17_tpu-8.config --model_dir=training
```

Provenance: **Documented** as comments. **Not an active instruction.** `generate_tfrecord.py` is not in this repo and was not at `research/object_detection/generate_tfrecord.py` on the pinned commit. `model_main_tf2.py` does exist at `research/object_detection/model_main_tf2.py` on that commit. The pipeline config file is not in `object_detection_py`.

Commit `b53f138` replaced a broken commented invocation (`pipeline_config\-psth=...` and a truncated `--model_dir=traini`) with the flags above. The line stayed commented.

Expected splits, from the commented flags only: `images/test` with `images/test_labels.csv` → `test.record`; `images/train` with `images/train_labels.csv` → `train.record`. Provenance: **Documented** inside comments. Those paths are not in git.

## Integrations

| System | Purpose in the notes | Direction | Auth | Failure behaviour |
|---|---|---|---|---|
| conda | Create Python 3.9 env | Local tool | None recorded | Not described |
| pip | Install `.`, wget, LabelImg | Local tool | None recorded | Not described |
| protoc | Compile `object_detection/protos` | Local tool, via `use_protobuff.py` | None recorded | Not described |
| LabelImg | Draw boxes, which then become XML the next command reads | Local GUI | None recorded | Not described |
| TensorFlow models tree | Object Detection API, label map, `model_main_tf2.py`, model-builder test | Gitlink `tf2/models` | None. URL not stored | Clone does not fetch it. No `.gitmodules` |
| Pretrained saved model | Inference weights | Local directory named in the command | None recorded | Not described |
| wget (Python package) | Named install only | Unknown | Unknown | Not described |

No HTTP API, database, queue, mail, or cloud account appears in the repository.

## Important constraints

- Python 3.9 is the only interpreter version written down. Provenance: **Documented**.
- The training and TFRecord commands are comments. Provenance: **Documented**.
- The inference command uses one named checkpoint and the MSCOCO label map. No confidence threshold, device, or batch size is written. Provenance: **Documented** by omission — those knobs are **Unknown**.
- `.gitignore` ignores `*.exe`, `*.mp4`, `*.avi`, `*.mov`, `*.wmv`, `*.flv`, and `*.tiff`. Provenance: **Implemented** as a stock template. It is not evidence that those files exist.
- No secret, token, or `.env` file is in git.

## Requirements index

### FR-001 — Python 3.9 conda environment

Requirement: The reader can create and activate a conda environment named by a placeholder `{name}` using Python 3.9.

Who: developer. Trigger: following `readme.md`. Inputs: conda, a chosen name. Expected behaviour: an active Python 3.9 env. Outputs: a local conda env. Validation: none written. Errors: none written.

Evidence: `readme.md` lines that call `conda create` and `conda activate`.

Implementation: Not implemented in this repo (no `environment.yml`).

Confidence: High that the note says this. The note is not executable from git.

### FR-002 — Compile Object Detection protos

Requirement: `python use_protobuff.py object_detection/protos protoc` compiles the Object Detection protocol buffers.

Evidence: `readme.md`.

Implementation: Script not in this repo and not in the pinned `research/object_detection/` tree.

Confidence: High that the command is written. Low that a clone can run it. The script's behaviour is **Unknown**.

### FR-003 — Install the local package and numpy

Requirement: `python -m pip install .` then `conda install numpy`, then change into `research/object_detection`.

Evidence: `readme.md`.

Implementation: No `setup.py` or `pyproject.toml` in this repo. The installable tree is expected to come from the gitlink. Working-directory order in the readme puts `pip install .` before `cd`.

Confidence: Medium. The commands are documented. Which directory `.` refers to is **Requires Confirmation**.

### FR-004 — Model-builder test

Requirement: From `research/object_detection`, `python builders/model_builder_tf2_test.py` is the recorded test.

Evidence: `readme.md`. File exists on `tensorflow/models` @ `505c718`. Not a blob here. No result is recorded.

Implementation: Not run by anything in this repo.

Confidence: High that the note names that file.

### FR-005 — Image inference with SSD MobileNet V2

Requirement: `detect_from_image.py` is invoked with saved-model directory `ssd_mobilenet_v2_320x320_coco17_tpu-8\saved_model`, label map `.\data\mscoco_label_map.pbtxt`, and image directory `.\images`.

Evidence: `readme.md`.

Implementation: Script, weights, and images are not in git. The label map file exists on the pinned upstream tree, not in this repo.

Confidence: High for the command text. The script's flags, output format, and thresholds are **Unknown**.

### FR-006 — LabelImg

Requirement: The reader installs LabelImg with pip and starts `labelimg.exe`.

Evidence: `readme.md`.

Implementation: Not vendored. `.gitignore` ignores `*.exe`.

Confidence: High for the two lines. Class list and save format are **Unknown**, except that the next command is named `xml_to_csv.py`, which implies XML input. That implication is **Inferred**.

### FR-007 — XML to CSV

Requirement: `python xml_to_csv.py` runs after LabelImg.

Evidence: `readme.md`. No arguments.

Implementation: Script not in this repo or at `research/object_detection/xml_to_csv.py` on the pinned commit.

Confidence: High that the command is written. Input and output paths are **Unknown**.

### FR-008 — TFRecord generation (commented)

Requirement: When the comments are followed, `generate_tfrecord.py` writes `test.record` from `images/test_labels.csv` plus `images/test`, and `train.record` from `images/train_labels.csv` plus `images/train`.

Evidence: two commented lines in `readme.md`.

Implementation: **Not an active command.** Script not in git.

Confidence: High that the lines are comments. Whether this is a requirement is **Requires Confirmation**.

### FR-009 — EfficientDet training (commented)

Requirement: When the comment is followed, `model_main_tf2.py` trains with pipeline config `ssd_efficientdet_d0_512x512_coco17_tpu-8.config` and writes to `training`.

Evidence: commented line in `readme.md`, corrected by `b53f138`. `model_main_tf2.py` exists on the pinned upstream tree. The config file is not in this repo.

Implementation: **Not an active command.**

Confidence: High that the line is a comment. Training hyperparameters beyond those two flags are **Unknown**.

## Discrepancies

| Topic | Documentation | Implementation |
|---|---|---|
| Sonar files | Task scan listed `sonar-project.properties` and `sonarqube_scan.bat` | Absent from git history |
| Inference and labelling scripts | Readme invokes them | Absent from this repo and from `research/object_detection/` at `505c718` |
| `tf2/models` | Present as a path | Gitlink without `.gitmodules`; clone does not fill it |
| Training | Present in the readme | Commented out, including after the 2024-03-26 correction |
| Install order | `pip install .` then later `cd research/object_detection` | No package metadata in this repo to resolve `.` |

No earlier Silicon Ark document conflicts with this set. This is the first one.

## Unknown / Requires Confirmation

- Product owner, customer, and the kind of object being detected.
- Where the four missing scripts live, and whether they were ever committed.
- TensorFlow, CUDA, and protobuf versions.
- What `pip install wget` downloads.
- Whether `{name}` was a shared environment name.
- Whether W5 was abandoned.
- Whether the scan-host Sonar files belong in the project.
- Whether `tf2/models` should be a declared submodule of `tensorflow/models`.