Skip to content

README.md

Latest commit

 

History

History
245 lines (165 loc) · 8.16 KB

README.md

File metadata and controls

245 lines (165 loc) · 8.16 KB
Raw

YOLO NDJSON Converter

Convert YOLO NDJSON annotation exports to popular ML formats - fast, private, and cross-platform.

MIT License Platforms Homebrew Built with Tauri Rust TypeScript

CI codecov GitHub Release


YOLO NDJSON Converter demo

Select your Ultralytics NDJSON export, pick an output format, and get a ready-to-train ZIP - everything runs locally, nothing leaves your machine.

Table of Contents

YOLO NDJSON Converter is a desktop app that converts Ultralytics YOLO's NDJSON annotation exports into ready-to-use datasets for YOLO, COCO, Pascal VOC, and other ML formats. Select your file, pick a format, and get a ZIP with images, labels, and config files.

Features

  • 12 Output Formats - YOLO26 through Darknet, COCO JSON, Pascal VOC, TFRecord, CreateML
  • 6 Task Types - Detection, Segmentation, Semantic Segmentation, Pose Estimation, Classification, OBB
  • Parallel Downloads - 100 concurrent connections for fast image fetching
  • Privacy-First - Everything runs locally; your data never leaves your device
  • Cross-Platform - macOS, Windows, and Linux
  • ~5 MB Binary - Tauri + Rust keeps the app tiny compared to Electron alternatives

Supported Formats

Format Status Compatible Tasks
YOLO26 ✅ Detection, Segmentation, Semantic, Pose, Classification, OBB
YOLOv12 ✅ Detection, Segmentation, Pose, Classification, OBB
YOLO11 ✅ Detection, Segmentation, Pose, Classification, OBB
YOLOv9 ✅ Detection, Segmentation
YOLOv8 ✅ Detection, Segmentation, Pose, Classification, OBB
YOLOv7 ✅ Detection
YOLOv5 ✅ Detection, Segmentation, Classification
YOLO Darknet ✅ Detection, Classification
COCO JSON ✅ Detection, Segmentation, Pose
Pascal VOC XML ✅ Detection, Segmentation, Classification
CreateML JSON 🔜 Detection, Classification
TFRecord 🔜 Detection

Note on Semantic Segmentation: Semantic datasets are exported as polygon segmentation labels (identical in shape to instance-segmentation polygons). Only YOLO26 trains them as semantic (omit masks_dir so the loader rasterizes polygons → dense masks). Other YOLO versions, COCO, and Pascal VOC can still use the exported polygons as instance-segmentation annotations. Formats that cannot represent polygons (YOLO Darknet, CreateML, TFRecord) are rejected for semantic datasets.

Installation

Quick Install

Windows (PowerShell):

irm https://yolondjson.zip/install.ps1 | iex

macOS / Linux:

curl -fsSL https://yolondjson.zip/install.sh | sh

macOS (Homebrew):

brew tap amanharshx/tap
brew install --cask yolo-ndjson-converter

Or download the latest release directly from GitHub Releases.

Troubleshooting

Note: The app is not yet code-signed (Apple Developer account costs $99/year, Windows EV certificate ~$300/year). I'm planning to get these when I can afford them. For now, you may see security warnings:

macOS — "App is damaged and can't be opened"

Run this command in Terminal after installing:

xattr -cr "/Applications/YOLO NDJSON Converter.app"

Then open the app again.

Windows — "Windows protected your PC" (SmartScreen)
  1. Click "More info"
  2. Click "Run anyway"

Or: Right-click the .exe → Properties → Check "Unblock" → Apply

Auto Updates

The app supports automatic updates.

When a new version is released:

  1. Open the app
  2. Click Updates (top right)
  3. If a new version is available, click Update
  4. Restart the app to finish installing

Updates are downloaded securely from GitHub Releases and verified using cryptographic signatures.

Build from Source

Prerequisites: Rust, Bun, Tauri v2 prerequisites

git clone https://github.com/amanharshx/yolo-ndjson-zip.git
cd yolo-ndjson-zip
bun install
bun run tauri dev        # development
bun run tauri build      # local production build

Note: Local builds are unsigned and intended for development only. Official signed builds are generated automatically via GitHub Releases.

Note: The backend Sentry DSN (if set) is compiled in at build time via SENTRY_DSN_BACKEND.

Tests

# Rust unit tests
cd src-tauri && cargo test

# Frontend unit tests
bun run test

NDJSON Input Format

The app expects newline-delimited JSON with this structure:

{"type":"dataset","task":"detect","name":"My Dataset","class_names":{"0":"cat","1":"dog"}}
{"type":"image","file":"img1.jpg","url":"https://...","width":640,"height":480,"split":"train","annotations":{"bboxes":[[0,0.5,0.5,0.2,0.3]]}}
{"type":"image","file":"img2.jpg","url":"https://...","width":640,"height":480,"split":"valid","annotations":{"bboxes":[[1,0.3,0.4,0.1,0.2]]}}

Pose rows use [class_id, cx, cy, width, height, keypoints...]. Dataset records may include "kpt_shape":[number_of_keypoints, 2|3]. Add kpt_shape when a 2D keypoint payload length is divisible by both 2 and 3, such as hand-21 or dog-18, because its dimensions cannot be inferred safely.

Roadmap

Export Formats

  • YOLO (YOLOv5 → YOLO26)
  • COCO JSON
  • Pascal VOC XML
  • CreateML JSON (coming soon)
  • TFRecord (coming soon)

Task Types

  • Detection
  • Segmentation
  • Semantic Segmentation
  • Pose Estimation
  • Classification
  • OBB (Oriented Bounding Box)

Tech Stack

  • Frontend - React 19 + TypeScript, Tailwind CSS, Vite
  • Backend - Rust + Tauri v2
  • Package Manager - Bun

Releases & Versioning

This project uses automated releases.

  • Versions follow semantic versioning (MAJOR.MINOR.PATCH)
  • Merging changes into main automatically prepares the next release
  • Releases are built and published via GitHub Actions

All official binaries are available on the GitHub Releases page.

Update Security

All releases are cryptographically signed.

The built-in updater verifies signatures before installing updates to ensure authenticity and prevent tampering.

Contributing

Contributions are welcome! Whether it's a bug fix, new format, or documentation improvement - every bit helps. Please read the Contributing Guide before opening a pull request.

Security

To report a security vulnerability, please see SECURITY.md.

License

This project is licensed under the MIT License.