> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repli5.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Defect Generation

> Synthesize realistic, localized industrial defects onto defect-free (OK) part images with automatic COCO bounding boxes and segmentation masks.

## Overview

**Defect Generation** synthesizes realistic physical defects (scratches, dents, tears, stains, weld flaws, wrinkles) directly onto **defect-free (OK)** product photos.

For every generated image, the platform automatically computes the pixel-level difference against the untouched OK source image, blends the defect seamlessly into the part's native surface grain, and exports **COCO segmentation masks and 2D bounding boxes** (`annotations_coco.json`).

***

## Key Concepts: Presets & Templates

* **Preset:** Defines **one defect type**—its COCO class name, visual description and placement, optional reference close-up photos, and blending mode. You can configure up to **8 presets** per template (up to **5** in Combined mode).
* **Template:** Saves a collection of presets to your project so you and your team can reload the exact same defect suite across future datasets without re-entering descriptions.

***

## Step-by-Step Guide

**1. 1. Defect-Free (OK) Images — Select Source Photos**

In Card **1**, choose your defect-free (`OK`) base images:

* **Dataset tab:** Pick an uploaded dataset of OK part photos and select the specific images (or the entire dataset) you want to augment.
* **Upload tab:** Upload a single OK part image for quick testing and preset tuning.

**2. 2. Defect Templates & Presets — Configure Defects**

In Card **2 (Defect templates)**, load an existing project template from the **Template Bar** or create presets from scratch (click **+ New**):

* **Defect Class:** A short label used as the exported **COCO category name** (e.g., `scratch`, `dent`, `wrinkle`, `tear`). Presets that share the same Defect Class name automatically share the same COCO `category_id` in the exported dataset.
* **Defect Description & Placement:** One unified text box describing **what the defect looks like** (type, shape, depth, edges, color, contrast), **how big it is** (e.g., fraction of the part or cm/mm), and **where to place it** (using visible part landmarks). If you omit a location, the AI planner automatically selects a valid placement region on the part at random for each image.
* **Randomized Choice Groups:** You can vary appearance or placement across a batch within a single preset using flat curly-brace choices such as `a {shallow hairline scratch | deep gouge}, about {2% | 5%} of the part's length`.
* **Reference Defect Images *(Optional, up to 3)*:** Upload or select up to 3 close-up photos of a real defect. The model extracts the defect's **shape and texture** from the references without copying the reference photo's background color, lighting, or position.

**3. 3. Generation Mode & Advanced Options**

Configure how multiple presets are applied:

* **Separate Mode *(Default)*:** Generates **1 output image per preset** for each selected OK image (`N images × P presets = N × P tasks`). Best for building balanced single-defect training sets.
* **Combined Mode:** Stacks **all presets sequentially onto each OK image** (`N images = N tasks`, up to 5 presets). Best for multi-defect inspection scenarios.
* **Faithful Paste vs. Direct Replace:** *Faithful Paste (Default ON)* pastes only the ΔE-gated, low-pass change so the original photo's sensor grain and micro-texture show through. *Direct Replace (OFF)* replaces the defect patch directly with generated pixels (useful when the defect shifts seams or stitching).
* **Negative Decoy Paste *(Optional, Default OFF)*:** Pastes one unlabeled defect-free patch on a non-overlapping spot using the same blend edge. Keep **OFF** when training with OK images or low-contrast defects; enable only when training without OK images to suppress boundary false positives.

**4. 4. Summary, Credits & Launch**

In Card **3 (Summary)**:

1. Review the total task count and **Required credits** (`1 credit` per task).
2. Verify the **Evaluation Rubric Set** (defaults to `default_defect_generation`).
3. Click **Augment** to start generation.

***

## Writing Effective Defect Prompts

| Do (Recommended) | Avoid |
| :- | :- |
| **"a shallow linear scratch with bright bare metal and jagged edges, ≈3% of the part's longer side, on the top-left corner of the bracket"** | **"scratch"** *(no shape, contrast, or size information)* |
| **"a soft but clearly visible dent with a distinct bright highlight next to a dark shadow, borders fade out, no sharp rim"** | **"a subtle low-contrast mark somewhere on the part"** *(too faint to pass diff masking)* |
| **"an unbroken dark scuff line, equally dark from end to end, along the outer bezel edge"** | **Nested choice groups** *(use flat single-level choice groups only)* |

***

## Output Dataset & COCO Export Structure

When a Defect Generation job completes, its output dataset in the **Data Library** includes:

* `rgb_out/`: The synthesized defective part images (`NOK`).
* `rgb_raw/`: The original defect-free source images (`OK`).
* `instances/` & `semantics_rgb/`: Pixel-accurate defect masks derived from the OK-vs-NOK difference.
* `annotations_coco.json`: Ready-to-train COCO annotations containing `images`, `categories` (mapped from your **Defect Class** names), and `annotations` (`bbox`, `segmentation` polygons, and `area`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.