STATGATOR Consulting

Resources from the book

Darknet Data Structure

Section 21.1 · The file and object structures used by the chapter’s helper utilities.

Section 21.1

One foundation for the utilities.

The chapter uses two kinds of data: training datasets stored in folders, and inference detections supplied as objects in memory. Use the structure appropriate to the utility you are running.

Training data

Images and annotation files used by the Python visualizers and anchor calculator.

Inference data

Bounding boxes produced by a running model and passed to the runtime helper functions.

Input · Files on disk

Training Data Structure

Place one or more clip folders beneath the project folder. Each clip contains an images folder and a labels folder.

Example project folder
Project Folder

Clip 01

imagespart_001.jpgSource images
labelspart_001.txtMatching annotations

Clip 02

imagespart_001.jpgSource images
labelspart_001.txtMatching annotations

Clip N

imagespart_001.jpgSource images
labelspart_001.txtMatching annotations

Clip names and filenames are illustrative. Keep the required images and labels folder names lowercase.

Linux Terminal
statgator@computer:~/AI$ ls
Inspection_Project

statgator@computer:~/AI$ cd Inspection_Project
statgator@computer:~/AI/Inspection_Project$ ls
clip1  clip2  clip3

statgator@computer:~/AI/Inspection_Project$ cd clip1
statgator@computer:~/AI/Inspection_Project/clip1$ ls
images  labels

statgator@computer:~/AI/Inspection_Project/clip1$ cd images
statgator@computer:~/AI/Inspection_Project/clip1/images$ ls
part_001.jpg  part_002.jpg  part_003.jpg

statgator@computer:~/AI/Inspection_Project/clip1/images$ cd ../labels
statgator@computer:~/AI/Inspection_Project/clip1/labels$ ls
part_001.txt  part_002.txt  part_003.txt

statgator@computer:~/AI/Inspection_Project/clip1/labels$
Keep image and annotation names paired.

For example, images/part_001.jpg corresponds to labels/part_001.txt. The extension changes; the filename stem stays the same.

Inside an annotation file

Each object occupies one line, with five whitespace-separated values:

class_id  center_x  center_y  width  height
0         0.50      0.50      0.25   0.20

The class ID identifies the label. The other four values are normalized relative to the image dimensions. An image containing multiple labeled objects has multiple annotation lines.

The key distinction

Center versus upper-left.

Training annotations describe the box center. The inference class shown in the chapter describes the box’s upper-left corner. These positions are different, even when they describe the same box.

Training annotation · normalized
Center: (0.50, 0.50)Normalized width 0.25 · height 0.20Example image: 1920 × 1080 pixels
Inference object · pixels
Upper-left: (720, 432) pxWidth 480 px · height 216 pxExample image: 1920 × 1080 pixels
The same box, expressed two ways.

In this illustrative 1920 × 1080 image, the annotation describes a box centered at (960, 540) pixels. Its width is 480 pixels and height is 216 pixels, placing the upper-left corner at (720, 432).

Output · Objects in memory

Inference Data Structure

Darknet detections are supplied to these helpers as an array of BoundingBox handles:

Running AI modelarray<BoundingBox@>Runtime helper

Each object carries the detection’s identity, confidence, pixel coordinates, size, and display color. The @ notation denotes an object handle in the scripting examples.

class BoundingBox {
    int label_id;
    string label_name;
    float confidence;
    int x;
    int y;
    int width;
    int height;
    int label_color_r;
    int label_color_g;
    int label_color_b;
}
MembersMeaning
label_id, label_nameNumeric label ID and its name.
confidenceModel confidence from 0 to 1.
x, yUpper-left corner of the box, in pixels.
width, heightBox dimensions, in pixels.
label_color_r, label_color_g, label_color_bRed, green, and blue components used for display.
A member-name difference to watch for.

The Mini-Box Combiner listing uses probability for the incoming confidence value. If your local class uses confidence, substitute that member name as the chapter instructs.

Prepare your environment

Python & Required Libraries

The three Python utilities use Python 3 and third-party packages. Create a separate virtual environment for this project so changes to these packages do not affect other projects.

1. Check Python and create an environment

Use a currently supported Python 3 release compatible with the required libraries. Open a Linux terminal in your project folder:

python3 --version
python3 -m venv .venv
source .venv/bin/activate

Install Python 3 using your distribution’s package manager if it is missing. On Ubuntu or Debian, if environment creation reports that venv is unavailable, install python3-venv; python3-pip may also be needed.

Before activation, Linux commonly uses python3. Once this environment is active, python refers to its Python interpreter.

2. Install the libraries

In the same Linux terminal, with the environment active, run:

python -m pip install --upgrade pip
python -m pip install numpy matplotlib opencv-python
python -m pip check
UtilityThird-party packages
Bounding Box VisualizerNumPy, Matplotlib, OpenCV
Grid / Stride VisualizerOpenCV
Anchor CalculatorNumPy, OpenCV

os, sys, and argparse are included with Python; do not install them separately. The visualizers require a desktop session that can display windows. The inference scripting examples are not Python programs.

3. Check and update packages when needed

With the environment active in your Linux terminal, check for updates and save the working versions before upgrading:

python -m pip list --outdated
python -m pip freeze > requirements-working.txt
python -m pip install --upgrade numpy matplotlib opencv-python
python -m pip check

Updates are optional. Test on a copy of your dataset afterward. To restore the saved package versions, create and activate a fresh environment, then run python -m pip install -r requirements-working.txt.

Type deactivate when finished. When opening a new Linux terminal, return to the project folder and run source .venv/bin/activate before using these commands.

These commands run on your computer. See the official Python packaging guide.

Before you begin

Match the utility to your data.

  • Python dataset utilities: provide the project folder with the clip, images, and labels structure above.
  • Bounding Box Visualizer and Anchor Calculator: the chapter assumes all dataset images have the same resolution.
  • Inference helpers: supply the bounding-box objects from your own model output. File folders are not the input to these functions.
  • Different local formats: adapt the file access or object members to your software while preserving the utility’s logic.

Based on Section 21.1 of the book. Filenames and coordinate illustrations are explanatory examples; the confidence-member note is drawn from Section 21.6.

The guide behind the codeFrom the page
to the plant floor.Practical Guide to AI Computer Vision Integration in Industrial ManufacturingExplore the Book