ICMarking
Synthetic

# ICMarkingSynthetic 1.0

Synthetic images of IC package markings support defect detection and automatic labeling. The balanced collection contains 6,000 images from 40 openly licensed source photographs, with defect-free counterparts and construction-derived labels. It includes good, scratch, contamination, missing text, smeared text and combined images; it is not evidence of factory readiness.

## Start here

1. Open `examples/01_browse.ipynb` to inspect images and labels.
2. Open `examples/02_statistics.ipynb` to reproduce the composition counts.
3. Run `python examples/03_train_yolo.py --help` for the two training protocols.
4. Run `python examples/04_face_crop.py --help` to verify or recreate face crops.

Install `numpy==1.26.4 pillow pandas==2.2.3 matplotlib jupyter`; training additionally needs `ultralytics`. Notebooks have saved outputs. Run scripts from this folder.

| Folder or file | Contents |
|---|---|
| images/, masks/ | Full images and renderer support masks, by split |
| labels/, labels_polygons/, labels_coco/ | YOLO boxes, YOLO polygons, COCO JSON for COCO tools |
| face_crop/ | Matching cropped images, boxes, polygons and training YAML |
| image_classes.csv | One class and split row per balanced image |
| splits/ | Source-disjoint and product-matched membership CSVs |
| provenance/ | Complete JSONL read by examples/load.py; flat CSV; auxiliary clean counterparts |
| supplement_cosmetic/ | Separate cosmetic examples and their CSV |
| examples/ | Executed notebooks, loading, training and crop scripts |
| docs/ | FORMATS.md and preserved validation results |
| dataset*.yaml | Full-image Ultralytics configurations |
| SOURCES.csv | Source authors, licenses and modifications |
| DATASET_CARD.md | Scope, composition and limitations |
| croissant.json | Machine-readable catalog for Croissant tools |
| CHECKSUMS.sha256 | File-integrity hashes |
| LICENSE-IMAGES.txt, LICENSE-ANNOTATIONS.txt | Image and annotation license texts |

Images: CC BY-SA 4.0. Annotations and provenance: CC BY 4.0. Preserve source attribution. Masks are renderer support, not guaranteed exhaustive changed-pixel masks.

Citation: Md Sami Ul Hoque and Nasser Kehtarnavaz, ICMarkingSynthetic, 2026. Reserved DOI: 10.5281/zenodo.23600809.

Copyright (c) 2026 Md Sami Ul Hoque and Nasser Kehtarnavaz

# Files and annotation formats

Images are 8-bit grayscale PNGs. The source-disjoint train/val/test folders contain 6,000 balanced images. A capture group shares one clean capture; keep every member together when splitting.

YOLO box rows: `class center_x center_y width height`, normalized by full image width and height. Class IDs 0, 1, 2, 3 mean scratch, contamination, missing text and smeared text. Good images have empty labels; combined images have separate defect boxes, not a fifth box class.

YOLO polygon rows: `class x1 y1 x2 y2 ...`, also normalized. External contours can omit holes and smaller disconnected regions. COCO files use pixel-space boxes and polygons and are read by COCO tools.

`provenance/records.jsonl` stores the complete nested record for each balanced image; `examples/load.py` and generator regeneration read it. `provenance/counterparts/records.jsonl` resolves the 18 clean counterparts outside the balanced set. `provenance/records.csv` projects both sets into Excel-friendly columns; filter `in_balanced_6000 == yes` before counting. Component types, severities and mechanisms are ordered semicolon lists. Seeds are 64-bit integers: use string or uint64 columns, not floating point.

`face_x1`, `face_y1`, `face_x2`, `face_y2` are the recorded crop corners, identical to `roi_xyxy`. They already include the six-pixel margin and frame clipping. Do not add padding again. The raw face boundary cannot always be recovered by subtracting padding, because clipping loses information. `examples/04_face_crop.py` uses the exact recorded crop and shifts/clips annotations.

`splits/source_disjoint.csv` maps source IDs to splits. `splits/product_matched.csv` maps image IDs to splits while keeping capture groups together. `image_classes.csv` combines both protocols. Ultralytics does not read split CSV directly: its product-matched YAML contains image paths generated from these same rows. Run training from the relevant full-image or face_crop folder.

`SOURCES.csv` retains all fields from the source attribution records. `supplement_cosmetic/manifest.csv` retains nested fields as JSON strings in CSV cells. Its 467 images are not part of the balanced 6,000. `croissant.json` is the standard catalog consumed by Croissant tools. No other JSON document is merely a second human-readable description.

The provenance `sha256` field is a 16-character prefix of a decoded-pixel hash. `CHECKSUMS.sha256` stores full hashes of encoded files. These are different checks. Renderer masks are not exhaustive changed-pixel support; this limitation is retained rather than repaired silently.

## One complete record

```json
{
  "image_id": "TVIC02_C000_scratch",
  "split": "train",
  "pm_split": "train",
  "source_id": "TVIC02",
  "capture_group": "TVIC02_C000",
  "capture": {
    "profile": "aoi",
    "angle_deg": 1.98,
    "scale": 1.006,
    "tx": 3.4,
    "ty": -0.6,
    "gain": 1.062,
    "gamma": 1.064,
    "bias": 3.9,
    "blur": 0.39,
    "noise": 3.6
  },
  "roi_xyxy": [
    173,
    48,
    473,
    265
  ],
  "marking_technology": "laser",
  "label": "scratch",
  "cosmetic": null,
  "is_combined_fault": false,
  "component_classes": [
    "scratch"
  ],
  "components": [
    {
      "class": "scratch",
      "mechanism": "abrasion_double_track",
      "severity_label": "low",
      "severity_value": 0.25,
      "mask_px": 2636,
      "parameters": {
        "length_fraction": 0.631,
        "reject_floor_retry_index": 0,
        "envelope_width_px": 11.14,
        "grooves": 6,
        "gate_duty": 0.69,
        "marking_overlap_fraction": 0.057,
        "scratch_p50": 171.82546997070312,
        "marking_p50": 255.0,
        "psf_sigma": 0.75
      }
    }
  ],
  "instances": [
    {
      "class": "scratch",
      "component": 0,
      "instance": 0,
      "bbox_xyxy": [
        225,
        62,
        446,
        115
      ],
      "area": 2525,
      "contrast": 73.6,
      "visible": true,
      "polygon": [
        225.0,
        78.0,
        226.0,
        79.0,
        231.0,
        79.0,
        232.0,
        78.0,
        245.0,
        79.0,
        247.0,
        77.0,
        250.0,
        77.0,
        253.0,
        79.0,
        259.0,
        79.0,
        260.0,
        78.0,
        262.0,
        80.0,
        266.0,
        79.0,
        273.0,
        80.0,
        278.0,
        79.0,
        280.0,
        77.0,
        284.0,
        77.0,
        287.0,
        80.0,
        290.0,
        77.0,
        294.0,
        77.0,
        295.0,
        80.0,
        299.0,
        80.0,
        304.0,
        78.0,
        306.0,
        83.0,
        307.0,
        81.0,
        319.0,
        82.0,
        320.0,
        83.0,
        322.0,
        82.0,
        327.0,
        83.0,
        330.0,
        81.0,
        333.0,
        83.0,
        347.0,
        80.0,
        353.0,
        81.0,
        355.0,
        79.0,
        353.0,
        77.0,
        354.0,
        76.0,
        362.0,
        76.0,
        364.0,
        74.0,
        368.0,
        77.0,
        367.0,
        78.0,
        362.0,
        78.0,
        361.0,
        79.0,
        363.0,
        81.0,
        365.0,
        80.0,
        369.0,
        81.0,
        371.0,
        79.0,
        372.0,
        80.0,
        374.0,
        79.0,
        376.0,
        81.0,
        382.0,
        81.0,
        383.0,
        80.0,
        388.0,
        81.0,
        391.0,
        77.0,
        393.0,
        77.0,
        396.0,
        80.0,
        399.0,
        79.0,
        401.0,
        80.0,
        416.0,
        76.0,
        422.0,
        76.0,
        426.0,
        73.0,
        432.0,
        74.0,
        434.0,
        72.0,
        443.0,
        74.0,
        445.0,
        72.0,
        445.0,
        70.0,
        443.0,
        68.0,
        429.0,
        68.0,
        428.0,
        69.0,
        421.0,
        69.0,
        416.0,
        71.0,
        412.0,
        71.0,
        411.0,
        74.0,
        409.0,
        73.0,
        402.0,
        76.0,
        396.0,
        76.0,
        393.0,
        73.0,
        383.0,
        73.0,
        382.0,
        72.0,
        379.0,
        73.0,
        376.0,
        71.0,
        351.0,
        72.0,
        341.0,
        69.0,
        339.0,
        71.0,
        330.0,
        71.0,
        329.0,
        72.0,
        328.0,
        68.0,
        315.0,
        68.0,
        312.0,
        70.0,
        309.0,
        69.0,
        307.0,
        71.0,
        305.0,
        70.0,
        298.0,
        72.0,
        295.0,
        71.0,
        293.0,
        72.0,
        292.0,
        71.0,
        284.0,
        71.0,
        278.0,
        73.0,
        271.0,
        73.0,
        270.0,
        72.0,
        263.0,
        72.0,
        262.0,
        73.0,
        257.0,
        72.0,
        256.0,
        73.0,
        254.0,
        72.0,
        251.0,
        75.0,
        248.0,
        72.0,
        232.0,
        72.0,
        231.0,
        73.0,
        226.0,
        73.0
      ]
    }
  ],
  "clean_counterpart": "TVIC02_C000_good",
  "image": "images/train/TVIC02_C000_scratch.png",
  "mask": "masks/train/TVIC02_C000_scratch.png",
  "changed_px": 4007,
  "changed_outside_face_px": 0,
  "seed": 1902019745343097344,
  "generator_version": "icmarkingsynthetic-generator-1.0",
  "sha256": "0c6a51c7e3313d74"
}
```

# ICMarkingSynthetic

Authors: Md Sami Ul Hoque and Nasser Kehtarnavaz, Embedded Machine Learning Laboratory, University of Texas at Dallas.

Purpose: research on synthetic marking defects, detection and automatic labeling. Defects are cause-derived image-formation approximations, not first-principles material simulations. This archive contains synthetic images from openly licensed source photographs, not real evaluation frames. Missing and smeared text lack real-image evaluation in the reported study. Results are not evidence of factory readiness.

Composition:
```json
{
  "by_class": {
    "good": 1000,
    "scratch": 1000,
    "contamination": 1000,
    "missing_text": 1000,
    "smeared_text": 1000,
    "combined": 1000
  },
  "source_disjoint": {
    "train": 3605,
    "val": 1204,
    "test": 1191
  },
  "product_matched": {
    "train": 4569,
    "val": 716,
    "test": 715
  }
}
```

Saved masks represent renderer support. They are not guaranteed to contain every changed pixel. In the recovered counterpart subset, 18 of 38 pairs contain all changes of at least two gray levels within a one-pixel dilation of the saved mask; all 38 changed-pixel counts match provenance. Masks were preserved, not repaired. Polygons describe external contours and may omit holes or smaller disconnected regions. The sha256 provenance field is a 16-character prefix of the decoded pixel hash, not a PNG-file hash; use CHECKSUMS.sha256 for file integrity.

See SOURCES.csv for source licenses and modifications; no source photograph is asserted to be public domain merely because it is openly accessible.

Copyright (c) 2026 Md Sami Ul Hoque and Nasser Kehtarnavaz