> ## 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** on **the Repli5 platform** synthesizes realistic physical defects (scratches, dents, tears, stains, weld flaws, wrinkles) directly onto **defect-free (OK)** product photos.

For every generated image, **the Repli5 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 paste/blend settings. You can configure up to **8 presets** per template in Separate mode (up to **5** in Combined mode).
* **Template:** Saves a collection of presets so you and your team can reload the exact same defect suite across future datasets. Clicking **Load template** lists all templates saved to the active project as well as your personal templates.

***

## 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 *(Default)*:** Pick an uploaded dataset of OK part photos from your library or active project, and select specific images on the page or the **entire dataset**.
* **Upload tab:** Upload a single OK part image from your computer for quick testing and preset tuning.

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

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

* **Defect Class:** A short label (up to 40 characters) 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` across the dataset.
* **Defect Description & Placement:** One unified text box (with no character limit) 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 picks a suitable spot on the part at random for each image.
* **Enhance Button:** Click **Enhance** below the description box to have the AI expand a brief note into a detailed, production-ready defect description tailored to your Defect Class and reference images.
* **Randomized Choice Groups:** Use flat curly-brace choices such as `a {shallow hairline scratch | deep gouge}, about {2% | 5%} of the part's length` to pick one option at random for each generated image.
* **Reference Images *(Optional, up to 3)*:** Upload up to 3 close-up photos of a real defect (`PNG`, `JPEG`, or `WEBP`). Only the defect's **shape and texture** are copied—never its background color, lighting, or position. When reference images are attached, the text description becomes optional.
* **Paste & Blend Controls:**
  * **Faithful paste *(Default ON)*:** Pastes only the ΔE-gated, low-pass change so the original photo's sensor grain and micro-texture show through. Turn **OFF** to paste the generated defect region directly (useful when moving existing seams or stitching).
  * **Blend *(Optional)*:** When unchecked, the defect is applied at full strength (`100%`). Check **Blend** to specify a custom strength range between `10%` and `100%` (e.g., `50 to 70 %`), drawn randomly per image.

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

In Card **3 (Summary)**, configure how multiple presets are applied:

* **Separate Mode *(Default)*:** Outputs **1 image per preset** for each selected OK image (`N images × P presets = N × P tasks`, up to 8 presets). Best for building balanced single-defect training sets.
* **Combined Mode:** Applies **all presets onto each OK image** (`N images = N tasks`, up to 5 presets). Best for multi-defect inspection scenarios.
* **Negative Decoy Paste *(Optional, Default OFF)*:** Pastes one unlabeled defect-free patch on a non-overlapping spot of the surface using the same blend edge. Keep **OFF** by default when training with OK images or on low-contrast defects; enable only when training without OK images to suppress paste-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 *Defect generation*, which scores `Defect Realism`, `Surface Continuity`, and `Scale & Geometry`).
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 `.json` 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.