Object detection

Draw boxes around objects. Each sample is one image plus one Pascal VOC XML file that lists the objects in it. There is no labels CSV: the ingestor reads the image list and the classes straight from the XML files.

Ingest with the CLI

Lay out each split as shown in Folder layout, then ingest the training data and the test data:

tracebloc data ingest ./visdrone-train --task object_detection --name visdrone_train --intent train --holds open_data
tracebloc data ingest ./visdrone-test --task object_detection --name visdrone_test --intent test --holds open_data

--holds open_data marks the dataset as open data. If your data is about patients, pass --holds patient_data; if it was generated, pass --holds synthetic_data. Leave --holds out on a terminal and the CLI asks; in a script, the dataset is marked as patient data. The mark decides which use case types you can create on the dataset. There is no --label-column: the classes come from the XML files. On a terminal, tracebloc data ingest ./visdrone-train works the task out from the folder; see Guided ingest. --target-size WxH, with the letter x, for example 1920x1080, is the size every image has to be; without it, the CLI takes the most common size among your images. See Image resolution. The [1920, 1080] default in the ingest.yaml table below applies only to Helm ingests.

Folder layout

/data/shared/visdrone/
├── images/
│   ├── 0000001_02999_d_0000005.jpg
│   └── ...
└── annotations/
    ├── 0000001_02999_d_0000005.xml
    └── ...

With the CLI, the dataset folder is on your machine (./visdrone-train). With Helm, it sits on the shared volume (/data/shared/...).
Both folders must have exactly these names and sit side by side.
Images and annotations pair by file stem: images/frame01.jpg belongs to annotations/frame01.xml. Every image needs its XML and every XML needs its image.
All images share one extension (.jpg, .jpeg or .png; default .jpg) and one resolution. The ingestor copies them unchanged and does not resize.

Annotation format (Pascal VOC)

<?xml version="1.0" encoding="UTF-8"?>
<annotation>
    <folder>images</folder>
    <filename>frame01.jpg</filename>
    <source>
        <database>Unknown</database>
        <annotation>PASCAL VOC</annotation>
    </source>
    <size>
        <width>1920</width>
        <height>1080</height>
        <depth>3</depth>
    </size>
    <segmented>0</segmented>
    <object>
        <name>car</name>
        <pose>Unspecified</pose>
        <truncated>0</truncated>
        <difficult>0</difficult>
        <bndbox>
            <xmin>871</xmin>
            <ymin>572</ymin>
            <xmax>925</xmax>
            <ymax>664</ymax>
        </bndbox>
    </object>
    <!-- one <object> per box -->
</annotation>

Every element shown is required:

Element	Rule
`folder`, `filename`	Non-empty text.
`source/database`, `source/annotation`	Non-empty text.
`size/width`, `size/height`, `size/depth`	Positive integers. `width` and `height` must equal the actual image dimensions.
`segmented`	`0` or `1`.
`object/name`	The class. Non-empty, with no spaces and no `:` (`traffic_light`, not `traffic light`); one such name fails the whole ingest. Class names are case-sensitive at ingest, so `Car` and `car` count as two classes: spell each class the same way in every file.
`object/pose`	Non-empty text (`Unspecified` is fine).
`object/truncated`	`0` or `1`.
`object/difficult`	A non-negative integer. Values other than `0`/`1` are accepted with a warning.
`object/bndbox`	Integer `xmin`, `ymin`, `xmax`, `ymax` with `xmin < xmax`, `ymin < ymax`, all non-negative, and `xmax`/`ymax` within the declared image size. A box with area below 10 pixels produces a warning.

An XML file with no <object> is accepted with a warning, but its image is skipped: it is not ingested and does not act as a background (negative) example.

Labeling tools such as CVAT and Label Studio often export float coordinates (871.5). The ingestor rejects them, so round every coordinate to an integer before you ingest. pose, truncated and difficult must be valid, but training ignores them: it reads only name, bndbox and size.

ingest.yaml

apiVersion: tracebloc.io/v1
kind: IngestConfig
category: object_detection
table: visdrone_train
intent: train
images: /data/shared/visdrone/images/
annotations: /data/shared/visdrone/annotations/

Field	Required	Meaning
`images`	yes	The `images/` folder.
`annotations`	yes	The `annotations/` folder. The record list comes from here.
`csv`, `json`	must not be set	Object detection has no manifest; the config is rejected if either is present.
`label`	leave out	Classes come from `object/name`.
`target_size`	no	`[width, height]` every image must have. Default `[1920, 1080]` (Helm only; the CLI reads it from your first image). Set it to your images’ real size, for example `[448, 448]`.
`spec.file_options.extension`	no	`.jpg`, `.jpeg` or `.png`. Default `.jpg`.
`spec.file_options.min_size`	no	Minimum `[width, height]`. Default `[32, 32]`.
`color_mode`, `bit_depth`	no	`RGB` or `grayscale`; `8` or `16`.

How records are stored

One record per image, not per box. The stored label of an image is its class histogram (for example car:3 motor:1). It must fit in 255 characters; an image with so many distinct classes that it does not fails the ingest. Because records are per image, the dataset summary reports class counts in boxes while the record count is the number of images. Data ids are content hashes, so re-running a failed ingest re-uses its rows.

What the ingestor checks

Check	Rejects
File type (images)	Files under `images/` with an extension other than the configured one, or mixed extensions.
File type (annotations)	Files under `annotations/` that are not `.xml`.
Pascal VOC XML	Any XML that breaks the rules in the table above.
File pairing	Images without a matching `<stem>.xml`, and XML files without a matching image.
Image resolution	Images whose size differs from `target_size`, mixed resolutions, images below `min_size`, unreadable files.
Label diversity	Fewer than two distinct classes across all `object/name` values. The training data and the test data are checked separately.

Plus the checks every ingest runs. A record is copied only when both its image and its XML copy succeed.

Training and test data

Ingest the training data and the test data separately (--intent train and --intent test). The classes in the test data must be a subset of the classes in the training data. If the test data has a class the training data lacks, it does not appear in the test dataset list when you define the use case. The ingest does not catch this. Each split must also have at least two classes on its own.

Size limit

One tracebloc data ingest takes at most 1 GiB in total and 500 MiB per file. If your dataset is larger:

Save the images as JPEG instead of PNG.
Lower the resolution: resize every image to one smaller size, and scale the box coordinates in the XML files to match.
Use fewer images.

For datasets that stay above the limit, see Size limit.

Sample dataset

The template ships one 1920×1080 aerial traffic frame from the public VisDrone dataset with its VOC annotation (classes such as car and motor). The ingest.yaml above ingests it with no overrides.

Next steps

Ingest the data: Prepare Data
Shared rules for every template: Dataset templates

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Ingest with the CLI

Folder layout

Annotation format (Pascal VOC)

ingest.yaml

How records are stored

What the ingestor checks

Training and test data

Size limit

Sample dataset

Next steps

​Ingest with the CLI

​Folder layout

​Annotation format (Pascal VOC)

​ingest.yaml

​How records are stored

​What the ingestor checks

​Training and test data

​Size limit

​Sample dataset

​Next steps

Ingest with the CLI

Folder layout

Annotation format (Pascal VOC)

ingest.yaml

How records are stored

What the ingestor checks

Training and test data

Size limit

Sample dataset

Next steps