Vision Systems & Engineering
Annotation Formats
How COCO JSON, Pascal VOC XML, YOLO text files and related formats store boxes, polygons and masks, how COCO's compressed run-length encoding works, and what is lost when annotations are converted from one format to another.
beginner
An annotation format is the file layout in which a dataset stores its labels: which image each label belongs to, the class, and the geometry as a box, polygon, mask or set of keypoints. Several layouts, each introduced with a dataset or a detector, serve as exchange formats between annotation tools, datasets and training code. They differ in coordinate conventions as well as syntax, so the same four numbers can describe different rectangles, and a conversion can quietly move every box.
Purpose
A format fixes three things: how files are organized (one file per dataset, per image or per object), how geometry is written (corners or centres, pixels or fractions of the image, 0- or 1-based indices, polygons or rasters), and which extra flags exist (crowd, difficult, truncated, void). The bounding box article covers the box parameterizations themselves. This article compares the formats, explains COCO’s compressed run-length encoding (RLE), which no other article describes, and measures what a chain of conversions loses.
Core Capabilities
The common formats
- COCO JSON. One JSON file per split; the detection layout (
images,annotationsandcategories, with polygon or RLEsegmentation,area,iscrowdand a 0-indexed[x, y, width, height]bbox) is described in the COCO article, which reads a file in it. The COCO API’smask.pystates the box convention precisely:bbox=[0 0 1 1]encloses the first pixel, so corners lie on pixel edges. The data format page also defines keypoint, stuff, caption and DensePose annotations; stuff stores one RLE mask per category present in an image. - COCO results. Detector outputs are a flat JSON array of records with
image_id,category_id,bboxorsegmentation, andscore. The results page recommends rounding box coordinates to the nearest tenth of a pixel to keep files small, and asks for instance masks as RLE produced by the API’sencode(). - COCO panoptic. Each image has a PNG of segment ids and a JSON record of
segments_infothat gives each id its category,iscrowd,bboxandarea. Void pixels are 0, and an RGB-decoded PNG gives ids as (data format page). Panoptic quality is scored on these files. - Pascal VOC XML. One XML file per image, with the image size and per-object
name,truncated,difficultand abndboxofxmin,ymin,xmax,ymax. As the Pascal VOC article describes, these are 1-based inclusive pixel indices, to which the evaluation code adds 1 for every width and height, and segmentation is stored separately as PNG label maps with a void value of 255. - YOLO text files (Ultralytics). One
*.txtfile per image, one row per object,class x_center y_center width height. The values are normalized to 0–1, withx_centerandwidthdivided by the image width andy_centerandheightby its height, and classes start at 0. An image without objects needs no file. A segmentation row is<class-index> <x1> <y1> ...with at least three normalized points. The Ultralytics docs add that detect-format rows carry no polygon, and a segment dataset whose box and polygon counts differ is rejected with aValueErrorwhen its labels load. A YAML file names the image folders and class names, and an NDJSON variant puts a dataset record and one record per image, with the same normalized rows, into a single file (Ultralytics docs, tag v8.4.212). This is a label format, not the YOLO detector. - Other dataset formats. Open Images uses CSV files with normalized
XMin,XMax,YMin,YMax. Cityscapes stores its fine annotations as JSON files of polygons and also as PNG images “where pixel values encode labels” (cityscapesScripts README), with scripts that rasterize the polygons into train-id and instance-id PNG images and convert the PNG annotations to COCO’s panoptic format. SA-1B stores each mask in COCO RLE in per-image JSON files. LVIS follows COCO’s JSON layout and adds fields for verified-absent and not-exhaustively-labelled categories. KITTI labels 3D boxes with truncation and occlusion labels. - Tool exports. Annotation tools such as CVAT and LabelMe each make their own choices of format, as Image Annotation notes; Label Studio is another such tool.
Run-length encoding and its compressed string
As the COCO article describes, uncompressed RLE stores the lengths of alternating runs, starting with a run of zeros, over the mask read in column-major order (top to bottom, then left to right). mask.py gives the example , whose counts are . A mask whose first pixel is set starts with a zero-length run, so becomes . The area is the sum of the second, fourth, … counts. The JSON form {"size": [h, w], "counts": [...]} is uncompressed RLE.
The compressed form replaces the list with a string. rleToString in maskApi.c, which its comment calls “Similar to LEB128 but using 6 bits/char and ascii chars 48-111”, works as follows:
- From the fourth count on (
if(i>2)), it stores the difference from the count two places back, so a mask whose column profile changes slowly gives small numbers. Since runs of zeros and runs of ones alternate, this compares like with like. - It writes each number in groups of 5 bits, least significant first. The sixth bit (
0x20) marks “more groups follow”, and the 5th data bit of the last group (0x10) acts as the sign, because differences can be negative. - It adds 48 to each 6-bit value, which gives the printable characters
0too. That range includes the backslash, which JSON escapes.
rleFrString inverts the steps, sign-extending the last group and adding back the count two places earlier. Area, unions and intersections can be computed on the runs without decoding (mask.py), and maskApi.c computes the bounding box and IoU from the runs too. rleToBbox tracks the column and row of the first and last pixel of each run of ones, and when such a run crosses from one column into the next it sets the box to the full image height. That is correct: such a run covers the bottom of one column and the top of the next. In mask.py’s words, the size of the RLE is proportional to the number of boundaries in the y direction, which for simple shapes is in the object’s area .
Minimal Example
The first script ports the encoder, decoder, area, box and string functions from maskApi.c at commit 8c9bcc3, with the COCO API’s BSD licence text that the licence requires. It tests them on synthetic masks: a disc, a ring with a hole, a two-part object whose second part is a full-height bar (so a run of ones crosses a column), a thin diagonal bar starting at the top-left pixel (so its counts begin with 0), and discs of radius 8 to 64. For each mask it counts the pixels and counts that fail to round-trip, compares the run-length area and box with the pixels, and checks what a transposed mask or a row-major reader does. It then compares sizes in bytes of a polygon outline (traced by scikit-image’s find_contours through pixel-centre crossings, in COCO’s frame, 2 decimals), the uncompressed and compressed RLE objects as compact JSON, and a 1-bit PNG of the whole image written by Pillow.
import os
os.environ["OMP_NUM_THREADS"] = os.environ["OPENBLAS_NUM_THREADS"] = "1"
import io, json
import numpy as np
from PIL import Image
from skimage.measure import find_contours, label, euler_number
# The RLE functions below are ported to Python from common/maskApi.c of the COCO API
# (github.com/cocodataset/cocoapi, commit 8c9bcc3), which carries this licence:
#
# Copyright (c) 2014, Piotr Dollar and Tsung-Yi Lin
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice, this
# list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# The views and conclusions contained in the software and documentation are those
# of the authors and should not be interpreted as representing official policies,
# either expressed or implied, of the FreeBSD Project.
def rle_encode(m): # rleEncode: runs over the column-major vector, zeros first
t = m.ravel(order="F")
cnts, p, c = [], 0, 0
for v in t:
if v != p:
cnts.append(c); c = 0; p = v
c += 1
cnts.append(c)
return cnts
def rle_decode(cnts, h, w): # rleDecode
vals = np.arange(len(cnts)) % 2
return np.repeat(vals, cnts).astype(np.uint8).reshape((h, w), order="F")
def rle_area(cnts): # rleArea: the odd-numbered entries count ones
return sum(cnts[1::2])
def rle_to_bbox(cnts, h, w): # rleToBbox: [x, y, w, h] without decoding
m = (len(cnts) // 2) * 2
if m == 0:
return [0, 0, 0, 0]
xs, ys, xe, ye, cc = w, h, 0, 0, 0
for j in range(m):
cc += cnts[j]
t = cc - j % 2
y = t % h; x = (t - y) // h
if j % 2 == 0:
xp = x
elif xp < x: # a run of ones crosses a column: full height
ys, ye = 0, h - 1
xs, xe, ys, ye = min(xs, x), max(xe, x), min(ys, y), max(ye, y)
return [xs, ys, xe - xs + 1, ye - ys + 1]
def rle_to_string(cnts): # rleToString: LEB128-like, 5 data bits per char, chars 48-111
s = []
for i, x in enumerate(cnts):
if i > 2:
x -= cnts[i - 2] # from the fourth count on, store the change from two counts back
more = True
while more:
c = x & 0x1F
x >>= 5
more = (x != -1) if (c & 0x10) else (x != 0)
if more:
c |= 0x20
s.append(chr(c + 48))
return "".join(s)
def rle_fr_string(s): # rleFrString
cnts, p = [], 0
while p < len(s):
x, k, more = 0, 0, True
while more:
c = ord(s[p]) - 48
x |= (c & 0x1F) << 5 * k
more = bool(c & 0x20); p += 1; k += 1
if not more and (c & 0x10):
x |= -1 << 5 * k # sign-extend a negative change
if len(cnts) > 2:
x += cnts[-2]
cnts.append(x)
return cnts
# Synthetic masks with known geometry: four shapes in a 48 x 64 image, four discs in 160 x 160.
H, W = 48, 64
r, c = np.mgrid[0:H, 0:W]
d2 = (r - 24) ** 2 + (c - 32) ** 2
masks = {
"disc": (r - 24) ** 2 + (c - 30) ** 2 <= 12 ** 2,
"ring": (d2 <= 14 ** 2) & (d2 > 7 ** 2),
"two-part": ((r >= 4) & (r <= 15) & (c >= 6) & (c <= 17)) | ((c >= 50) & (c <= 53)),
"diag bar": np.abs(c - r * (W - 1) / (H - 1)) < 1.0, # starts at pixel (0, 0)
}
r, c = np.mgrid[0:160, 0:160]
for R in (8, 16, 32, 64):
masks[f"disc r={R}"] = (r - 80) ** 2 + (c - 80) ** 2 <= R ** 2
masks = {k: v.astype(np.uint8) for k, v in masks.items()}
def tight_box(m): # [x, y, w, h] from the pixels themselves
rows, cols = np.nonzero(m)
return [int(cols.min()), int(rows.min()), int(cols.max() - cols.min() + 1),
int(rows.max() - rows.min() + 1)]
def polygon_json(m): # boundary through pixel-centre crossings, COCO frame (+0.5)
polys = [(p[:, ::-1] - 1 + 0.5).round(2).ravel().tolist()
for p in find_contours(np.pad(m, 1), 0.5)]
return json.dumps(polys, separators=(",", ":"))
def png_bytes(m): # 1-bit PNG written by Pillow
buf = io.BytesIO()
Image.fromarray(m.astype(bool)).save(buf, format="PNG")
return len(buf.getvalue())
js = lambda o: len(json.dumps(o, separators=(",", ":")).encode())
print("mask.py examples:", rle_encode(np.array([[0, 0, 1, 1, 1, 0, 1]], np.uint8).T),
rle_encode(np.array([[1, 1, 1, 1, 1, 1, 0]], np.uint8).T))
rg, tp, br = masks["ring"], masks["two-part"], masks["diag bar"]
print("data: ring components", label(rg, connectivity=1).max(), "euler", euler_number(rg, connectivity=1),
"| two-part components", label(tp, connectivity=1).max(),
"| bar pixel (0,0) =", br[0, 0], "first count", rle_encode(br)[0])
print(f"{'mask':11s} {'dec.px':>6s} {'str':>3s} {'area':>5s} {'sum':>5s} {'rle box':>16s} "
f"{'tight box':>16s} {'T same':>6s} {'C-order px':>10s}")
for k, m in masks.items():
h, w = m.shape
cn = rle_encode(m)
bad_px = int((rle_decode(cn, h, w) != m).sum())
back = rle_fr_string(rle_to_string(cn))
bad_str = sum(a != b for a, b in zip(cn, back)) + abs(len(cn) - len(back))
t_same = rle_encode(m.T) == cn
c_order = int((np.repeat(np.arange(len(cn)) % 2, cn).reshape((h, w)) != m).sum())
print(f"{k:11s} {bad_px:6d} {bad_str:3d} {rle_area(cn):5d} {int(m.sum()):5d} "
f"{str(rle_to_bbox(cn, h, w)):>16s} {str(tight_box(m)):>16s} {str(t_same):>6s} {c_order:10d}")
print()
print(f"{'mask':11s} {'counts':>6s} {'polygon':>7s} {'RLE list':>8s} {'RLE str':>7s} {'PNG':>5s} {'backslash':>9s}")
for k, m in masks.items():
h, w = m.shape
cn = rle_encode(m)
s = rle_to_string(cn)
print(f"{k:11s} {len(cn):6d} {len(polygon_json(m)):7d} {js({'size': [h, w], 'counts': cn}):8d} "
f"{js({'size': [h, w], 'counts': s}):7d} {png_bytes(m):5d} {s.count(chr(92)):9d}")
Output:
mask.py examples: [2, 3, 1, 1] [0, 6, 1]
data: ring components 1 euler 0 | two-part components 2 | bar pixel (0,0) = 1 first count 0
mask dec.px str area sum rle box tight box T same C-order px
disc 0 0 441 441 [18, 12, 25, 25] [18, 12, 25, 25] False 596
ring 0 0 464 464 [18, 10, 29, 29] [18, 10, 29, 29] False 726
two-part 0 0 336 336 [6, 0, 48, 48] [6, 0, 48, 48] False 576
diag bar 0 0 94 94 [0, 0, 64, 48] [0, 0, 64, 48] False 184
disc r=8 0 0 197 197 [72, 72, 17, 17] [72, 72, 17, 17] True 0
disc r=16 0 0 797 797 [64, 64, 33, 33] [64, 64, 33, 33] True 0
disc r=32 0 0 3209 3209 [48, 48, 65, 65] [48, 48, 65, 65] True 0
disc r=64 0 0 12853 12853 [16, 16, 129, 129] [16, 16, 129, 129] True 0
mask counts polygon RLE list RLE str PNG backslash
disc 51 1013 179 84 154 0
ring 89 1785 262 127 187 0
two-part 27 1477 113 62 95 0
diag bar 128 2370 346 157 96 0
disc r=8 35 693 152 70 143 0
disc r=16 67 1333 266 102 194 0
disc r=32 131 2768 466 166 288 0
disc r=64 259 5600 903 296 449 0
Every round trip is exact, and the run-length area and box equal those counted on the pixels: hypothesis H1 held for all eight masks, and so did the area, box and hand-example checks (mask.py’s two examples come out as printed in its comment). The data checks held too: the ring is one component with Euler number 0 (one hole), the two-part object has two components, and the bar’s first pixel is set, so its counts start with 0. The two-part object’s box spans rows 0–47 because its bar fills whole columns, the case handled by rleToBbox’s full-height branch. The four shapes in the 48 × 64 (rows × columns) image give different counts when transposed, and a row-major decode gets more than a hundred pixels wrong: the column-major check held for each. The centred discs in the square image are symmetric under transposition, so for them both readings agree; the check was planned for the four shapes only.
The sizes follow the boundary count. A disc of radius spans columns, and each column adds two boundaries, so its counts number (35 to 259 here). The compressed object grows by less than a factor of two per doubling of the radius, while the area grows by a factor of four, in line with mask.py’s statement. The decimal list grows faster: it spends several characters on every count, while the string, which stores differences from two counts back, needs little more than one character per count for the largest disc (296 bytes for 259 counts, size field included). Hypothesis H2 held for all eight masks: the compressed object was smaller than the uncompressed one each time. No string happened to contain a backslash. Our polygons are several times larger than the compressed RLE objects for every mask, because find_contours places a vertex at every pixel-edge crossing; COCO’s instance outlines average 24.5 vertices per instance, as Image Annotation reports, so this comparison says more about our tracing than about polygons. The PNG carries a fixed header and codes the whole image. It is larger than the compressed RLE object for every mask except the diagonal bar, which crosses all 64 columns and so needs 128 counts.
The second part continues the script. It draws 2,000 COCO boxes with sub-pixel corners in a image, sizes log-uniform between 2 and 256 pixels, and sends them through COCO → VOC (1-based inclusive integers) → YOLO (normalized centre and size with VOC’s +1, written and read back at six decimals) → COCO. No source fixes how COCO corners become integers, so two rules are run: “round” moves each edge to the nearest pixel edge, “outward” takes every pixel the box touches.
As a second VOC → YOLO path it runs convert() from darknet’s voc_label.py, darknet’s VOC-to-YOLO script. That function takes the centre as and the width as . Against the VOC box’s 0-based extent , this centre is 0.5 px to the left and the width is 1 px short. So, by our derivation, the decoded left edge is unchanged and the right edge moves 1 px left. The script also skips difficult objects and classes outside its list. IoU between continuous boxes follows the intersection over union definition.
# Continues the script above.
def iou(a, b): # continuous [x0, y0, x1, y1] boxes, rows of a 4 x N array
iw = np.clip(np.minimum(a[2], b[2]) - np.maximum(a[0], b[0]), 0, None)
ih = np.clip(np.minimum(a[3], b[3]) - np.maximum(a[1], b[1]), 0, None)
inter = iw * ih
return inter / ((a[2] - a[0]) * (a[3] - a[1]) + (b[2] - b[0]) * (b[3] - b[1]) - inter)
def coco_to_voc(b, rule): # 0-based continuous xywh -> 1-based inclusive integer corners
x0, y0, x1, y1 = b[0], b[1], b[0] + b[2], b[1] + b[3]
if rule == "round":
x0, y0, x1, y1 = np.round(x0), np.round(y0), np.round(x1), np.round(y1)
else: # "outward": every pixel the box touches
x0, y0, x1, y1 = np.floor(x0), np.floor(y0), np.ceil(x1), np.ceil(y1)
return np.array([x0 + 1, y0 + 1, x1, y1]) # xmin, ymin, xmax, ymax
def voc_to_yolo(v, W, H): # VOC's +1: the box covers [xmin - 1, xmax] in 0-based units
x0, y0, x1, y1 = v[0] - 1, v[1] - 1, v[2], v[3]
return np.array([(x0 + x1) / 2 / W, (y0 + y1) / 2 / H, (x1 - x0) / W, (y1 - y0) / H])
def darknet_convert(v, W, H): # convert() of darknet's scripts/voc_label.py (public domain)
xmin, ymin, xmax, ymax = v
x = (xmin + xmax) / 2.0 - 1
y = (ymin + ymax) / 2.0 - 1
return np.array([x / W, y / H, (xmax - xmin) / W, (ymax - ymin) / H])
def write_read(y): # a label file stores six decimals
return np.vectorize(lambda v: float(f"{v:.6f}"))(y)
def yolo_to_corners(y, W, H): # normalized cx cy w h -> 0-based continuous corners
return np.array([(y[0] - y[2] / 2) * W, (y[1] - y[3] / 2) * H,
(y[0] + y[2] / 2) * W, (y[1] + y[3] / 2) * H])
W, H, N = 640, 480, 2000
rng = np.random.default_rng(0)
size = np.exp(rng.uniform(np.log(2), np.log(256), N)) # sqrt(w h), log-uniform
aspect = np.exp(rng.uniform(np.log(0.5), np.log(2), N))
bw, bh = size * np.sqrt(aspect), size / np.sqrt(aspect)
boxes = np.array([rng.uniform(0, W - bw), rng.uniform(0, H - bh), bw, bh]) # COCO xywh
orig = np.array([boxes[0], boxes[1], boxes[0] + boxes[2], boxes[1] + boxes[3]])
octave = np.digitize(size, 2.0 ** np.arange(1, 9)) - 1
print("data: inside image", bool((orig[:2] >= 0).all() and (orig[2] <= W).all() and (orig[3] <= H).all()),
f"| size {size.min():.3f}-{size.max():.3f} | per octave", np.bincount(octave, minlength=7).tolist())
for rule in ("round", "outward"):
voc = coco_to_voc(boxes, rule)
at_voc = np.array([voc[0] - 1, voc[1] - 1, voc[2], voc[3]])
final = yolo_to_corners(write_read(voc_to_yolo(voc, W, H)), W, H)
dark = yolo_to_corners(write_read(darknet_convert(voc, W, H)), W, H)
loss = 1 - iou(orig, final)
mean_bin = np.array([loss[octave == k].mean() for k in range(7)])
centre = np.array([np.exp(np.log(size[octave == k]).mean()) for k in range(7)])
slope = np.polyfit(np.log(centre), np.log(mean_bin), 1)[0]
dw = (final[2] - final[0]) - (dark[2] - dark[0])
print(f"\n{rule}: COCO->VOC max error {np.abs(at_voc - orig).max():.4f} px, IoU loss mean "
f"{(1 - iou(orig, at_voc)).mean():.5f} max {(1 - iou(orig, at_voc)).max():.5f}")
print(f"{rule}: VOC->YOLO->COCO max error {np.abs(final - at_voc).max():.2e} px, IoU loss max "
f"{(1 - iou(at_voc, final)).max():.2e}")
print(f"{rule}: whole chain IoU loss mean {loss.mean():.5f} max {loss.max():.5f}")
print(f"{rule}: mean loss per octave", " ".join(f"{v:.5f}" for v in mean_bin),
f"| slope {slope:.3f}")
print(f"{rule}: darknet max|dw-1| {np.abs(dw - 1).max():.2e}, max|dx0| {np.abs(final[0] - dark[0]).max():.2e}, "
f"max|dx1+1| {np.abs(dark[2] - final[2] + 1).max():.2e}, "
f"max|dcx+0.5| {np.abs((dark[0] + dark[2]) / 2 - (final[0] + final[2]) / 2 + 0.5).max():.2e}")
# The tight boxes of the eight masks are whole pixels.
for rule in ("round", "outward"):
e_voc = e_yolo = l_max = 0.0
for k, m in masks.items():
h, w = m.shape
b = np.array(tight_box(m), float)[:, None]
o = np.array([b[0], b[1], b[0] + b[2], b[1] + b[3]])
v = coco_to_voc(b, rule)
av = np.array([v[0] - 1, v[1] - 1, v[2], v[3]])
f = yolo_to_corners(write_read(voc_to_yolo(v, w, h)), w, h)
e_voc, e_yolo = max(e_voc, np.abs(av - o).max()), max(e_yolo, np.abs(f - av).max())
l_max = max(l_max, (1 - iou(o, f)).max())
print(f"mask boxes, {rule}: COCO->VOC max error {e_voc:.4f} px, VOC->YOLO->COCO {e_yolo:.2e} px, "
f"chain IoU loss max {l_max:.2e}")
Output:
data: inside image True | size 2.002-255.381 | per octave [294, 276, 298, 275, 282, 292, 283]
round: COCO->VOC max error 0.5000 px, IoU loss mean 0.09209 max 0.59851
round: VOC->YOLO->COCO max error 3.20e-04 px, IoU loss max 4.80e-04
round: whole chain IoU loss mean 0.09209 max 0.59857
round: mean loss per octave 0.30571 0.16217 0.08773 0.04438 0.02245 0.01109 0.00576 | slope -0.957
round: darknet max|dw-1| 3.20e-04, max|dx0| 6.40e-04, max|dx1+1| 6.40e-04, max|dcx+0.5| 4.80e-04
outward: COCO->VOC max error 0.9999 px, IoU loss mean 0.15121 max 0.66722
outward: VOC->YOLO->COCO max error 3.20e-04 px, IoU loss max 4.00e-04
outward: whole chain IoU loss mean 0.15120 max 0.66720
outward: mean loss per octave 0.44833 0.28169 0.15862 0.08459 0.04504 0.02211 0.01115 | slope -0.894
outward: darknet max|dw-1| 3.20e-04, max|dx0| 6.40e-04, max|dx1+1| 6.40e-04, max|dcx+0.5| 4.80e-04
mask boxes, round: COCO->VOC max error 0.0000 px, VOC->YOLO->COCO 3.20e-05 px, chain IoU loss max 3.84e-06
mask boxes, outward: COCO->VOC max error 0.0000 px, VOC->YOLO->COCO 3.20e-05 px, chain IoU loss max 3.84e-06
Almost all of the drift comes from the integer step. Rounding moves an edge by up to half a pixel and the outward rule by up to one pixel. The six-decimal YOLO step adds at most px, which is half of of the 640-pixel width. The data check on the boxes held (all inside the image, every size octave populated), and so did the check on the masks’ tight boxes: they are whole pixels already, so the VOC step leaves them unchanged and only the six decimals touch them.
The mean IoU lost over the chain roughly halves with each doubling of box size. The fitted slope against size is −0.957 for rounding and −0.894 for the outward rule, so hypothesis H3, a slope between −1.2 and −0.8, held under both rules. Our derivation of why: moving an edge of a box of side by changes its area by about , a fraction , so the loss scales as . At the smallest sizes the loss is bounded, which flattens the fit. The outward rule loses more at every size; in our reading this is because it can only enlarge a box, so its edge errors add up rather than cancel. Boxes 2 to 4 pixels across lose 31% (round) or 45% (outward) of their IoU on average, and the worst box loses 0.599 or 0.667, so a detection that matched the original box exactly would fall below an IoU threshold of 0.5 against the converted one. Boxes of 128 pixels and more lose 0.6% (round) or 1.1% (outward).
Darknet’s convention behaves as derived: under both rules the decoded width is 1 px less than with VOC’s +1 to within px, so H4 held. The left edge is unchanged and the right edge 1 px further left, both to within px, and the centre sits 0.5 px to the left.
Process note. The four hypotheses and every bar (zero differences for H1, an integer comparison for H2, for H3, px for H4) were written before any script for this example existed. A separate reachable-value script, an independent implementation run on the same masks, seed and rules before the plan was fixed, printed the reachable values for H2–H4, all within their bars. Details the batch plan left open were fixed before the pilot: the two rounding rules; the full-height bar and the corner-starting diagonal bar among the masks; byte counts for all eight masks, with the counts and backslash columns; find_contours polygons; the two transposition prints; both mask.py examples; the box sampling; mean, maximum and per-octave losses; darknet’s edge and centre offsets; mask boxes in their own image sizes; and no pycocotools cross-check, since it is not installed. The pilot ran this script unchanged, and the first run, shown here, repeated it with identical output. After the first run, one comment changed: the second block’s first line, which named the pilot’s file layout, now reads “Continues the script above.”; the edited script was run twice and printed output identical to the first run’s. It ran with NumPy 2.3.5, scikit-image 0.25.2 and Pillow 12.0.0 in under a second (approximate).
Converting Between Formats
Each conversion has its own losses:
- Index base and integers. VOC’s 1-based inclusive integers and COCO’s 0-based continuous corners differ by one pixel in width and half a pixel in position, and VOC cannot hold sub-pixel corners; the example measures both effects, and Pascal VOC shows the +1 near the 0.5 IoU threshold.
- Normalization. Normalized values must be multiplied by the size of the image they refer to, and their precision limits the round trip; six decimals are harmless at these image sizes.
- Geometry types. Converting a polygon to a mask rasterizes it. The COCO API’s
rleFrPolyupsamples the polygon by a factor of 5 before sampling its boundary, so other rasterizers can differ along edges, as COCO notes. Going from mask to polygon needs a contour tracer and loses holes unless the format allows several rings. Boxes cannot be turned back into outlines. - Flags.
iscrowd,difficult,truncated, void labels, LVIS’s negative and not-exhaustive lists and Open Images’ group-of boxes have no counterpart in YOLO text files; darknet drops difficult objects altogether. Evaluation that relies on these flags changes after such a conversion. - Empty images. In YOLO’s layout an image without objects has no label file, so a missing file has to be read as “no objects”, not as an unlabelled image.
We suggest a round trip as a check after any conversion on a sample: convert back, compare boxes by IoU and masks pixel by pixel, and count objects per image and class.
Ecosystem and Integrations
The COCO API (pycocotools, with MATLAB and Lua versions) reads COCO files, decodes masks and runs the official evaluation, as the COCO article lists, and mask.py encodes RLE. Its core RLE code is in C, and the results page notes that encoding outside MATLAB or Python is possible but unsupported. Ultralytics provides converters from COCO to its format and from mask images to polygon rows. cityscapesScripts converts Cityscapes polygons to train-id label images and its PNG annotations to COCO panoptic files.
Alternatives
Datasets that need richer structure than these formats keep their own layouts and converters. Examples are tracks, 3D boxes in KITTI, per-image mask files in SA-1B, and hierarchical labels in Open Images. For dense semantic labels, VOC and Cityscapes use PNG label maps rather than per-object masks (image segmentation).
Versions and Compatibility
The COCO API code described here is commit 8c9bcc3 of cocodataset/cocoapi, under the Simplified BSD licence. The Ultralytics statements come from its documentation at tag v8.4.212, the latest release as of November 2026; the repository is AGPL-3.0, and no Ultralytics code is reproduced here. Darknet’s voc_label.py is public domain. As of November 2026, LabelMe is GPL-3.0 and CVAT is MIT-licensed. The example ran with NumPy 2.3.5, scikit-image 0.25.2 and Pillow 12.0.0; newer releases exist (NumPy 2.5.4, scikit-image 0.26.0, Pillow 13.0.0 as of November 2026), and nothing here is claimed about them.
Limitations
- Conventions live outside the files. A box file does not record whether its writer used continuous or inclusive coordinates; that is in the format’s documentation, a converter has to know it, and the example shows what a wrong guess costs.
- RLE is binary and per object. Each RLE mask is one binary layer, so overlapping instances need separate masks, and semantic or panoptic labels go into PNG label maps instead.
- Compressed strings are opaque. They depend on the image height and width given beside them, and can be read only with the COCO decoder or a port of it.
Related
- COCO
Microsoft's Common Objects in Context, a dataset of everyday scenes with per-instance segmentation masks for 80 object categories, plus keypoints, captions, stuff and panoptic labels, whose evaluation protocol became the standard benchmark for object detection.
- PASCAL VOC
The PASCAL Visual Object Classes challenge (2005–2012), whose 20-class datasets of Flickr photographs with bounding boxes and segmentations set the standard protocol for evaluating object detection.
- Image Segmentation
Dividing an image into regions by assigning every pixel to a segment, a class, or an object instance, the task behind semantic, instance, panoptic and interactive segmentation.
- Intersection over Union
The area where a predicted region and the ground truth overlap, divided by the area they cover together, the standard way to score localization in detection, segmentation, and tracking.
- SA-1B
Meta AI's Segment Anything 1-Billion dataset of 11 million licensed photographs and 1.1 billion class-agnostic masks, all generated automatically by SAM, with its released format, the automatic-generation recipe and how the released code's defaults differ from it, the mask-quality audit and its research licence.
- YOLO
A family of real-time one-stage object detectors, begun by Redmon et al. in 2016, that predict every box and class probability of an image in a single network pass; later versions from several groups added anchors, multi-scale heads, anchor-free heads and NMS-free training.
References
- COCO Consortium. COCO Data Format. Common Objects in Context (COCO) dataset website.
- COCO Consortium. Results Format, dataset/format-results.htm, cocodataset/cocodataset.github.io at commit 5e1c4da (source of the COCO website).
- Dollár, P. & Lin, T.-Y. (2015). COCO API, common/maskApi.c and common/maskApi.h, cocodataset/cocoapi at commit 8c9bcc3 (Simplified BSD License).
- Dollár, P. & Lin, T.-Y. (2015). COCO API, PythonAPI/pycocotools/mask.py, cocodataset/cocoapi at commit 8c9bcc3.
- Ultralytics. Object Detection Datasets Overview, docs/en/datasets/detect/index.md, ultralytics/ultralytics at tag v8.4.212 (November 2026).
- Ultralytics. Instance Segmentation Datasets Overview, docs/en/datasets/segment/index.md, ultralytics/ultralytics at tag v8.4.212 (November 2026).
- Darknet. scripts/voc_label.py, pjreddie/darknet at commit f6afaab (public domain).
- Cityscapes. cityscapesScripts README.md, mcordts/cityscapesScripts at commit 8b9cba9.