# ultralytics/json2yolo architecture

> Architecture diagram of the GitHub repository ultralytics/json2yolo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ultralytics/json2yolo
- Repository: https://github.com/ultralytics/json2yolo

## Overview

##### Project Type and Purpose
- This is an open-source, command-line Python toolkit for converting COCO-style JSON dataset annotations to the YOLO format. It is not a web service or full-stack app—it’s a lightweight data-conversion utility.

##### File Structure Analysis
- Top-level scripts:
- general_json2yolo.py – handles generic COCO/JSON → YOLO conversion
- labelbox_json2yolo.py – handles Labelbox-specific JSON → YOLO conversion
- utils.py – shared helper functions (e.g., JSON parsing, coordinate normalization, file I/O)
- requirements.txt – Python dependencies
- Metadata/configuration: .gitignore, LICENSE, README.md
- CI formatting workflow: .github/workflows/format.yml

##### Key Insights from README
- The core workflow is initiated via a CLI script (`convert.py` in docs, mapped to the two scripts above), invoked with `--json_dir` and `--save_dir` arguments.
- Designed to run on Linux, macOS, and Windows with Python ≥3.8.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    UserTerminal["User Terminal"]:::ext
    Runtime["Python Runtime (≥3.8)"]:::ext

    %% CLI Layer
    subgraph "CLI Layer"
        GeneralScript["general_json2yolo.py"]:::cli
        LabelboxScript["labelbox_json2yolo.py"]:::cli
    end

    %% Conversion Engine
    subgraph "Conversion Engine"
        Loader["JSON Loader"]:::engine
        Mapper["Annotation Mapper"]:::engine
        Transformer["Coordinate Transformer"]:::engine
        FileWriter["YOLO File Writer"]:::engine
    end

    %% Utils Module
    Utils["utils.py\n(shared helpers)"]:::engine

    %% File System
    subgraph "File System"
        InputDir["Input Dataset Directory\n(.json files)"]:::fs
        OutputDir["Output Labels Directory\n(.txt files)"]:::fs
    end

    %% External Dependencies
    ExternalDeps["Python stdlib &\nthird-party libs"]:::ext

    %% Metadata & Config
    subgraph "Project Metadata"
        README["README.md"]:::meta
        License["LICENSE"]:::meta
        Gitignore[".gitignore"]:::meta
        Requirements["requirements.txt"]:::meta
    end

    %% CI Workflow
    CI[".github/workflows/format.yml"]:::ci

    %% Data Flows
    UserTerminal -->|"invoke CLI"| Runtime
    Runtime -->|"executes script"| GeneralScript
    Runtime -->|"executes script"| LabelboxScript

    GeneralScript -->|"parse flags| json_dir/save_dir"| Loader
    LabelboxScript -->|"parse flags| json_dir/save_dir"| Loader

    Loader -->|"Parsed JSON"| Mapper
    Mapper -->|"Annotation Data"| Transformer
    Transformer -->|"Normalized coordinates| class IDs"| FileWriter
    FileWriter -->|"writes .txt files"| OutputDir

    InputDir -->|"provides .json files"| Loader

    %% Imports & Dependencies
    GeneralScript -->|"imports"| Utils
    LabelboxScript -->|"imports"| Utils
    Loader -->|"uses helpers"| Utils
    Mapper -->|"uses helpers"| Utils
    Transformer -->|"uses helpers"| Utils
    FileWriter -->|"uses helpers"| Utils

    GeneralScript -->|"uses runtime & libs"| ExternalDeps
    Utils -->|"uses runtime & libs"| ExternalDeps

    %% Metadata & CI references
    Runtime -->|"env & version info"| Requirements
    GeneralScript -->|"project docs"| README
    GeneralScript -.->|"license info"| License
    GeneralScript -.->|"ignore rules"| Gitignore
    CI -.->|"formatting checks"| Requirements

    %% Click Events
    click GeneralScript "https://github.com/ultralytics/json2yolo/blob/main/general_json2yolo.py"
    click LabelboxScript "https://github.com/ultralytics/json2yolo/blob/main/labelbox_json2yolo.py"
    click Utils "https://github.com/ultralytics/json2yolo/blob/main/utils.py"
    click Requirements "https://github.com/ultralytics/json2yolo/blob/main/requirements.txt"
    click README "https://github.com/ultralytics/json2yolo/blob/main/README.md"
    click License "https://github.com/ultralytics/json2yolo/tree/main/LICENSE"
    click Gitignore "https://github.com/ultralytics/json2yolo/blob/main/.gitignore"
    click CI "https://github.com/ultralytics/json2yolo/blob/main/.github/workflows/format.yml"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef engine fill:#ABEBC6,stroke:#333,stroke-width:1px
    classDef fs fill:#D5DBDB,stroke:#333,stroke-width:1px
    classDef ext fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef meta fill:#FADBD8,stroke:#333,stroke-width:1px
    classDef ci fill:#FDEBD0,stroke:#333,stroke-width:1px
```
