Project Data Format

A Micro-Seg project is a plain directory with a fully documented, versioned format. No database, no absolute paths, UTF-8 everywhere.

MyProject/
├── project.json        # what the project IS: config, categories
├── index.jsonl         # what it CONTAINS: image list + workflow metadata
├── .microseg/          # optional: plugin bindings + project params
└── objects/
    ├── images/         # content-addressed image bytes (sha256)
    └── annotations/    # one JSON sidecar per image

Design properties

• Content-addressed storage. Every image is identified by the SHA-256 of its raw bytes and stored under objects/images/<shard>/<hash><ext>. Duplicate imports are detected and rejected.
• Append-only index. index.jsonl is a log of full snapshot records; final state is last-record-wins. Updates never rewrite existing lines, which keeps diffs small and writes crash-safe.
• Atomic writes. All files are written via temp-file + fsync + rename.
• Git-friendly. Deterministic canonical JSON and append-only logs make projects practical to version and review.
• Strict validation. Projects are validated on open; corruption is reported instead of silently ignored.

Annotations

Each image’s annotations live in one JSON sidecar (objects/annotations/<shard>/<hash>.json). Coordinates are stored as fixed-point integers (stored = round(real × scale)) in the raw pixel space of the image.

Supported shape encodings:

Type	Encoding
bbox	[x, y, w, h]
rectangle	min/max corners + rotation_deg
ellipse	center + radii + rotation_deg
point / points	coordinate pairs
polyline	open vertex chain
polygon	closed vertex chain
mask	origin + size + run-length encoded bitmap

Every shape references a category defined in project.json. Categories are never physically deleted — they are deactivated, so old annotations always resolve.

Interoperability

Because the format is plain JSON with a published spec, it is straightforward to consume from Python, R or any other analysis pipeline — no export step required. CSV and XML export are additionally available from the app.

The complete field-level specification of format v1 is available on request — contact us.