Docs

What Labelyst reads, what each check does, and how the score is calculated.

Review and correct

Select a finding, inspect its local image, and edit the annotation. Free includes individual class edits, deletion, numeric box corrections, and automatic repairs. Pro adds bulk changes, polygon editing, undo and redo, and saved sessions. Downloads reflect accepted changes, with a separate repair manifest.

Free accepts files up to 500MB; Pro accepts files up to 1GB. A ZIP's uncompressed contents must also fit the active plan limit. Saved sessions stay in this browser and contain correction values. New purchases are shown only after the configured monthly and annual plans pass the live billing verification.

Supported input

CSV / TXT

Any CSV with a label column. Labelyst detects clear headers and preserves clear headerless files. Ambiguous first rows require confirmation before scoring.

JSON, flat array

A top-level array of objects, or an object with an "annotations" or "data" array.

JSONL / NDJSON

One JSON object per non-empty line. Malformed input reports the exact source line, and heterogeneous object fields are preserved.

JSON, COCO format

Detected automatically from the images/annotations/categories schema and flattened. Declared dimensions and broken image references are included in the health report.

ZIP, YOLO export

Validated labels/*.txt plus classes.txt or data.yaml. Detection, segmentation, pose, and oriented boxes are distinguished. Oriented boxes receive rotation-aware geometry and overlap checks.

XML / ZIP, Pascal VOC

Reads individual VOC XML annotations or a ZIP containing an XML file per image, including declared image dimensions.

JSON / ZIP, LabelMe

Reads LabelMe rectangles, polygons, and points from one JSON file or a multi-file dataset ZIP.

Parquet

Reads top-level scalar fields from uncompressed or Snappy Parquet files. Nested values and other compression codecs are rejected.

TFRecord

Reads CRC-checked TensorFlow Example records with one scalar value per feature. Generic TFRecord payloads, tensors, and sequence examples are rejected.

PCD / LAS

Reads ASCII PCD and uncompressed LAS point records. LAZ and binary PCD are not supported. Point-cloud checks do not assess CRS, spatial indexing, or sensor calibration.

ZIP, single file

A zip containing exactly one CSV, JSON, JSONL, or NDJSON file gets extracted and read normally.

ZIP, classification folders

Infers labels only from an unambiguous split/class/image or class/image hierarchy with at least two classes.

ZIP, segmentation folders

Pairs clear images and masks folders by relative path and checks missing pairs and dimensions. Mask class IDs remain limited without a palette or schema.

Interactive browser review supports up to 250,000 retained tabular records. Larger CSV, TXT, JSONL, and NDJSON inputs can run bounded local streaming regression checks up to a 5,000,000-record safety cap. File limits are 500MB Free or 1GB Pro; ZIP contents must remain within the same active-plan limit after decompression. Archives also allow up to 5,000 entries, and TIFF decoding is capped at 25 million pixels. These caps protect the browser tab from memory exhaustion and decompression bombs.

Preflight and coverage

Every upload pauses before scoring and shows the detected format, annotation type, record count, image count, ignored files, and coverage limits. Results are either fully supported, supported with limits, or rejected. A partial analysis is capped at 60 and cannot be presented as Excellent.

The 15 checks

Duplicate labels

Flags inconsistent spelling of the same class ("car" vs "Car" vs " car "), and exact duplicate annotation rows when a filename column is present. Repeated correct labels are normal and never flagged.

Naming consistency

Looks at unique class names, detects the majority naming style (snake_case, camelCase, PascalCase, kebab-case), and flags classes that don't match it.

Capitalization

Looks at unique class names, detects the majority capitalization style, and flags classes that don't match it.

Empty or invalid labels

Flags rows with a missing, blank, or null label.

Invalid characters

Flags invisible Unicode and control characters that can obscure a source label. Leading spaces and punctuation remain source data; CSV exports neutralize formula-like text separately.

Class balance

Flags severe imbalance when the largest class outnumbers the smallest by more than 10x. It is excluded for a confirmed numeric regression target.

Class coverage

Flags classes below the configured minimum annotation count. The default minimum is five and can be changed in the report. It is excluded for a confirmed numeric regression target.

Bounding boxes

Validates coordinates: negative values, zero or negative width/height, and for YOLO's normalized format, boxes that extend past the image edge.

Annotation distribution

Reports per-class and per-split size/aspect distributions, small or stretched boxes, crowded images, center heatmaps, heavy overlaps, and probable duplicate boxes.

Segmentation, OBB, and keypoints

Validates polygon bounds, area, self-intersection and overlap; RLE masks; rotated-box corners, bounds, angles and rotated IoU; and keypoint counts, visibility, skeleton references, and image bounds.

Dataset integrity

Finds missing image references, images without annotations, empty annotation files, duplicate image IDs, unreadable headers, unusual dimensions, and inconsistent media pairing.

Image quality

Fully decodes a bounded JPEG, PNG, GIF, BMP, WebP, or single-page TIFF sample in a Web Worker and flags darkness, overexposure, low contrast, blur, corruption, EXIF rotation, exact duplicates, and near duplicates.

Split balance

Compares class proportions across train, validation, and test paths to reveal missing or strongly shifted classes.

Dataset comparison

Diffs label counts and, when both versions contain image IDs and boxes, identifies individual annotations that were added, removed, or changed.

Taxonomy suggestions

Informational only, not scored. Groups labels by shared prefix, flags likely singular/plural pairs, and flags similar spellings, capped at 300 unique labels for performance.

Local quality gate

Run npm run quality -- dataset.zip --min-score 80 to apply the same analyzer in a terminal or CI job. Add --profile profile.json to reuse exported thresholds and --report report.json to save the result. For an ambiguous CSV, add --header present or --header absent.

The local CLI uses the Free 500MB limit until you run npm run quality -- auth YOUR_LICENSE_KEY. A verified Pro activation raises its local-file limit to 1GB. Files stay on your device; the activation check sends only license details.

Quality thresholds

Advanced mode exposes class, geometry, overlap, exposure, contrast, blur, crowding, and image-sampling thresholds. The score and findings recalculate immediately, and the selected profile is included in the JSON report so the result can be reproduced.

How the score works

A weighted calculation you can inspect

Each check produces a score from 0 to 100. Labelyst multiplies each applicable score by its weight, adds those results, and divides by the total applicable weight. The result is rounded to the nearest whole number.

Raw score = Σ(check score × weight) ÷ Σ(applicable weights)

Check	Weight	When it counts
Duplicate labels	15	Always included
Naming consistency	15	Always included
Capitalization	10	Always included
Empty or invalid labels	20	Always included
Invalid characters	15	Always included
Class balance	15	Classification targets only
Class coverage	10	Classification targets only
Bounding boxes	10	Included when boxes are present
Annotation distribution	10	Included when boxes are present
Split balance	10	Included when split differences are found
Dataset integrity	15	Included when images are inventoried
Image quality	15	Included when images can be decoded
Segmentation and keypoints	10	Included when these annotations are present
Cross-split leakage	15	Excluded when a split comparison cannot run

Unavailable checks: A check without the needed evidence is left out of both parts of the formula. It never lowers a score for data Labelyst could not assess.

Incomplete coverage: If the preflight report finds only partial media or format coverage, the final score is capped at 60 until the dataset can be fully checked.

Grades: Excellent is 90 to 100, Good is 75 to 89, Needs Improvement is 50 to 74, and Poor is below 50.

Not scored: Taxonomy suggestions and shared label prefixes are guidance only. They never change the score.

Every completed report repeats its included checks, scores, weights, and any cap beside the result.

Exports

The safe-repair preview lists every deterministic change before download. It removes empty-label and exact duplicate annotations, normalizes label variants, and clips intersecting axis-aligned boxes to known image boundaries. Fully invalid boxes and subjective findings stay in the review list. Corrected COCO, YOLO, Pascal VOC, and LabelMe files retain their source format. CSV, JSON, JSONL, PDF, portable HTML, and issue-manifest exports are also available. Repeated valid annotations are preserved, and CSV exports neutralize formula-like text in every column.

Privacy

Everything runs in your browser. No file, image, pixel, report, label, filename, or quality result is sent to a server. Image pixels are discarded immediately after measurement. If privacy analytics is configured, it counts page views and performance only, without cookies or dataset fields. Recent history stays in local browser storage and can be cleared from the landing page.

The same local-first boundary applies to repairs, reports, and evidence exports. A report leaves the device only when you download it or explicitly send it through an integration you configured.

Deployment checks

Production builds enforce compressed client-asset budgets. After deployment, run npm run load:test -- --url https://www.labelyst.com to measure success rate, throughput, and p50, p95, and p99 latency with bounded concurrency.