OpenDefectKit

Industrial Computer Vision Infrastructure for Python

OpenDefectKit is the missing infrastructure layer for industrial defect detection AI.

Every factory AI engineer rebuilds the same pipelines — annotation converters, augmentation scripts, dataset validators, edge exporters. OpenDefectKit ships all of it as a single pip install.

Install

pip install opendefectkit                    # core
pip install opendefectkit[benchmark]         # + model evaluation (requires PyTorch)
pip install opendefectkit[deploy]            # + ONNX edge export
pip install opendefectkit[all]               # everything

Quick Start

from opendefectkit.pipeline import DefectPipeline

pipeline = DefectPipeline(
    raw_data_dir="data/raw_annotations",
    output_dir="data/processed",
)
pipeline.run(steps=[
    "detect_format",
    "validate_annotations",
    "fix_annotations",
    "convert_to_yolo",
    "profile_dataset",
    "export_report",
])
# HTML report written to data/processed/dataset_report.html

Modules

CLI

# Detect annotation format
opendefectkit convert --input data/annotations/ --target yolo --output data/yolo/

# Profile a dataset
opendefectkit analyze --dataset data/yolo/ --output report.html

# Validate annotations
opendefectkit validate --dataset data/yolo/

# Generate synthetic defects
opendefectkit augment --images data/clean/ --defect crack --samples 200 --output data/augmented/

# Benchmark a model
opendefectkit benchmark --model runs/train/best.pt --dataset data/test/ --output benchmark.json

Defect Taxonomy

35 defect types across 6 categories: Surface Cracks, Corrosion, Surface Defects, Weld Defects, Coating Defects, Dimensional.

from opendefectkit.taxonomy import DefectTaxonomy

tax = DefectTaxonomy()

# Normalize raw labels from any source dataset
mapping = tax.map_labels(["rusty", "fracture", "pore", "undercutting"], method="fuzzy_match")
# {"rusty": "surface_rust", "fracture": "structural_crack", "pore": "porosity", "undercutting": "undercut"}

defect = tax.standardize("rust spot")
print(defect.id, defect.severity_class)  # CO-001  medium

weld_defects = tax.list_defects("Weld Defects")
# [DefectType(id='WD-001', name='porosity', ...), ...]

Synthetic Augmentation

from opendefectkit.augment import SyntheticDefectGenerator, IndustrialAugPipeline

# Generate crack images with paired YOLO labels
gen = SyntheticDefectGenerator(seed=42)
gen.add_cracks(
    clean_images_dir="data/clean/",
    output_dir="data/synthetic/cracks/",
    num_samples=500,
    crack_types=["hairline", "structural", "fatigue"],
    severity_range=(0.1, 0.9),
)

# Apply industrial augmentation transforms
pipeline = IndustrialAugPipeline(
    transforms=["random_lighting", "motion_blur", "industrial_noise", "jpeg_compression"]
)
pipeline.run(
    input_dir="data/synthetic/cracks/",
    output_dir="data/augmented/",
    multiplier=5,  # 5 augmented versions per image
)

Available transforms: random_lighting, motion_blur, jpeg_compression, perspective_warp, industrial_noise, surface_reflection.

Dataset Health Score

from opendefectkit.analyze import DatasetHealthScore

result = DatasetHealthScore("data/yolo/").run()
print(result)
# Dataset Health Score: 75/100
#
#   [PASS] (20pt) Min samples per class >= 100
#          Min samples: 312 check
#   [FAIL] (15pt) Validation split exists
#          No val/ or valid/ subdirectory
#   [PASS] (10pt) Duplicate images < 1%
#          Duplicates: 2/500 (0.4%)
#   [WARN] (20pt) Class imbalance ratio < 10:1
#          Imbalance ratio: 8.3:1 (need < 10:1)
#   ...
# Recommendation: To improve dataset quality: create a val/ subdirectory.

Edge Deployment

from opendefectkit.deploy import ONNXExporter, EdgeOptimizer, DEVICE_PROFILES

# Export YOLOv8 model to ONNX
exporter = ONNXExporter("runs/train/best.pt")
exporter.export(
    output_path="deploy/model.onnx",
    input_size=(640, 640),
    optimize_for="edge",
    quantize=True,
)

# Get device-specific recommendations
optimizer = EdgeOptimizer("deploy/model.onnx")
result = optimizer.profile_device("jetson_nano").optimize(target_latency_ms=33.0)
print(result.recommendations)
# ["Recommended input size: (416, 416)", "Target FPS: 30.0"]

optimizer.generate_deployment_package("deploy/package/")
# Creates deploy/package/deployment_package.zip with model + inference script + requirements.txt

Available device profiles: jetson_nano, jetson_orin, raspberry_pi_4, intel_nuc, generic_x86.

Who Uses This

Factory AI engineers who are tired of rebuilding:

• Annotation format converters for every new dataset
• Synthetic defect generators when real defect data is scarce
• Dataset validators that find the corrupt annotations before training
• Edge exporters that work with Jetson Nano and Raspberry Pi

Contributing

Fork the repo. To add defect types, extend the DEFECT_REGISTRY list in opendefectkit/taxonomy/defects.py following the existing DefectType dataclass pattern. To add format support, implement read_<format> in opendefectkit/convert/ and wire it into _converters.py. All contributions require tests in tests/. PR welcome.

License

MIT