# Conversion, lossiness, and reports
Not all annotation formats carry the same information. When you convert between
formats, some fields may not have an equivalent in the target format — that's
what panlabel calls "lossiness." Rather than silently dropping data, panlabel
tells you exactly what would be lost and asks you to opt in with `--allow-lossy`.
Scope reminder: panlabel focuses on mainstream/static-image 2D axis-aligned object-detection bbox conversion.
Segmentation, keypoints/pose, oriented boxes, video tracking IDs, and 3D/multisensor labels are out of first-class scope; richer structures are skipped/reported or handled as lossy.
Every `convert` command generates a report explaining what happened.
## Lossiness model
A conversion report issue has a severity:
- `warning`: real information loss risk; conversion is blocked unless `--allow-lossy` is set
- `info`: deterministic policy note; never blocks conversion
Format-level lossiness relative to IR:
- `ir-json`: lossless
- `coco`: conditional
- `ibm-cloud-annotations`: lossy
- `cvat`: lossy
- `label-studio`: lossy
- `labelbox`: lossy
- `scale-ai`: lossy
- `unity-perception`: lossy
- `tfod`: lossy
- `tfrecord`: lossy
- `vott-csv`: lossy
- `vott-json`: lossy
- `yolo`: lossy
- `yolo-keras`: lossy
- `yolov4-pytorch`: lossy
- `voc`: lossy
- `hf`: lossy
- `sagemaker`: lossy
- `labelme`: lossy
- `superannotate`: lossy
- `supervisely`: lossy
- `cityscapes`: lossy
- `marmot`: lossy
- `create-ml`: lossy
- `kitti`: lossy
- `via`: lossy
- `retinanet`: lossy
- `openimages`: lossy
- `kaggle-wheat`: lossy
- `automl-vision`: lossy
- `udacity`: lossy
- `datumaro`: lossy
- `wider-face`: lossy
- `oidv4`: lossy
- `bdd100k`: lossy
- `v7-darwin`: lossy
- `edge-impulse`: lossy
- `openlabel`: lossy
- `via-csv`: lossy
The format-level class is a general capability signal. Conversions are actually blocked only when the report contains one or more `warning` issues.
## JSON report shape
With `--report json`, output follows this shape:
```json
{
"from": "coco",
"to": "yolo",
"input": {"images": 10, "categories": 3, "annotations": 40},
"output": {"images": 10, "categories": 3, "annotations": 40},
"issues": [
{"severity": "warning", "stage": "analysis", "code": "drop_dataset_info", "message": "..."},
{"severity": "info", "stage": "source_reader", "code": "coco_reader_attribute_mapping", "message": "..."},
{"severity": "info", "stage": "target_writer", "code": "yolo_writer_float_precision", "message": "..."}
]
}
```
The `stage` field indicates where in the conversion pipeline the issue originates:
- `analysis`: lossiness analysis (warnings about data loss)
- `source_reader`: source format reader policy
- `target_writer`: target format writer policy
## Stable issue codes
These codes are designed to be stable for programmatic use.
### Warning codes
| `drop_dataset_info` | Dataset-level metadata is dropped |
| `drop_licenses` | License list is dropped |
| `drop_image_metadata` | Image metadata fields (license/date) are dropped |
| `drop_category_supercategory` | Category supercategory is dropped |
| `drop_annotation_confidence` | Annotation confidence values are dropped |
| `drop_annotation_attributes` | Annotation attributes are dropped |
| `drop_images_without_annotations` | Images without annotations will not appear in output |
| `drop_dataset_info_name` | `info.name` has no COCO equivalent |
| `coco_attributes_may_not_be_preserved` | Some COCO-tool roundtrips may not preserve nonstandard attributes |
| `label_studio_rotation_dropped` | Rotated Label Studio boxes are flattened to axis-aligned envelopes; angle is kept as `ls_rotation_deg` attribute |
| `labelbox_polygon_envelope_applied` | Labelbox polygons are flattened to axis-aligned bbox envelopes |
| `labelbox_unsupported_objects_skipped` | Labelbox non-detection objects were skipped while preserving image rows |
| `scale_ai_geometry_envelope_applied` | Scale AI polygons or rotated boxes were flattened to axis-aligned bbox envelopes |
| `unity_perception_unsupported_annotations_skipped` | Unity Perception non-bbox annotation blocks were skipped while preserving captures/images |
| `hf_metadata_lost` | HF metadata cannot represent full IR dataset metadata/licenses/supercategory fields |
| `hf_attributes_lost` | HF metadata drops image/annotation attributes outside its flat schema |
| `hf_confidence_lost` | HF metadata does not preserve annotation confidence |
| `cvat_writer_drop_unused_categories` | CVAT writer drops categories not referenced by any annotation from `<meta><labels>` |
| `collapse_multiple_categories_to_single_class` | Multiple categories collapsed to single class for single-class format (e.g. Kaggle Wheat) |
### Info codes
| `coco_reader_attribute_mapping` | COCO reader maps score→confidence and stores area/iscrowd as annotation attributes |
| `coco_writer_deterministic_order` | COCO writer sorts licenses/images/categories/annotations by ID |
| `coco_writer_score_mapping` | COCO writer maps IR confidence to the COCO score field |
| `coco_writer_area_iscrowd_mapping` | COCO writer reads area/iscrowd from attributes; defaults to bbox area and iscrowd=0 |
| `coco_writer_empty_segmentation` | COCO writer emits empty segmentation arrays for detection-only output |
| `tfod_reader_id_assignment` | TFOD reader deterministic ID policy |
| `tfod_writer_row_order` | TFOD writer deterministic row order |
| `tfrecord_reader_id_assignment` | TFRecord reader deterministic ID policy |
| `tfrecord_reader_payload_policy` | TFRecord reader supported payload/mapping policy |
| `tfrecord_writer_example_order` | TFRecord writer deterministic Example ordering policy |
| `tfrecord_writer_payload_policy` | TFRecord writer supported payload/mapping policy |
| `vott_csv_reader_id_assignment` | VoTT CSV reader deterministic ID policy |
| `vott_csv_reader_image_resolution` | VoTT CSV reader image dimension resolution from disk |
| `vott_csv_writer_row_order` | VoTT CSV writer deterministic row order |
| `vott_csv_writer_no_image_copy` | VoTT CSV writer does not copy image files |
| `vott_json_reader_id_assignment` | VoTT JSON reader deterministic ID policy |
| `vott_json_polygon_envelope_applied` | VoTT JSON reader flattened point/polygon-like geometry to bbox envelopes |
| `vott_json_writer_deterministic_order` | VoTT JSON writer deterministic ordering policy |
| `vott_json_writer_rectangle_policy` | VoTT JSON writer emits rectangle regions with `boundingBox` and corner points |
| `vott_json_writer_no_image_copy` | VoTT JSON writer does not copy image files |
| `cloud_annotations_reader_id_assignment` | IBM Cloud Annotations reader deterministic ID policy |
| `cloud_annotations_reader_image_resolution` | IBM Cloud Annotations reader image dimension resolution from disk |
| `cloud_annotations_writer_deterministic_order` | IBM Cloud Annotations writer deterministic ordering policy |
| `cloud_annotations_writer_normalized_coordinates` | IBM Cloud Annotations writer normalized coordinate mapping |
| `cloud_annotations_writer_no_image_copy` | IBM Cloud Annotations writer does not copy image files |
| `yolo_reader_id_assignment` | YOLO reader deterministic ID policy |
| `yolo_reader_class_map_source` | YOLO class map precedence/source note |
| `yolo_writer_class_order` | YOLO writer class index assignment policy |
| `yolo_writer_empty_label_files` | YOLO writer creates empty label files for unannotated images |
| `yolo_writer_float_precision` | YOLO normalized float and confidence precision policy (6 decimal places) |
| `yolo_writer_deterministic_order` | YOLO writer orders images and labels by file_name |
| `yolo_writer_no_image_copy` | YOLO writer creates only label files; images are not copied |
| `yolo_reader_split_handling` | YOLO reader split-aware layout: notes which splits were found and which were read |
| `yolo_writer_data_yaml_policy` | YOLO writer emits data.yaml with a names: mapping only (no split paths or nc) |
| `yolo_keras_txt_reader_id_assignment` | YOLO Keras-style TXT reader deterministic ID policy |
| `yolo_keras_txt_reader_class_map_source` | YOLO Keras-style TXT class-file precedence and fallback policy |
| `yolo_keras_txt_reader_image_resolution` | YOLO Keras-style TXT image dimension probing policy |
| `yolo_keras_txt_writer_class_order` | YOLO Keras-style TXT writer class ID assignment policy |
| `yolo_keras_txt_writer_deterministic_order` | YOLO Keras-style TXT writer deterministic row/box ordering policy |
| `yolo_keras_txt_writer_empty_rows` | YOLO Keras-style TXT writer emits image-only rows for unannotated images |
| `yolo_keras_txt_writer_no_image_copy` | YOLO Keras-style TXT writer does not copy image files |
| `voc_reader_id_assignment` | VOC reader deterministic ID assignment policy |
| `voc_reader_attribute_mapping` | VOC reader mapping of pose/truncated/difficult/occluded attributes |
| `voc_reader_coordinate_policy` | VOC reader coordinate policy (no 0/1-based adjustment) |
| `voc_reader_depth_handling` | VOC reader depth metadata handling note |
| `voc_writer_file_layout` | VOC writer XML path/layout policy |
| `voc_writer_no_image_copy` | VOC writer placeholder JPEGImages policy |
| `voc_writer_bool_normalization` | VOC writer boolean normalization policy |
| `label_studio_reader_id_assignment` | Label Studio reader deterministic ID assignment policy |
| `label_studio_reader_image_ref_policy` | Label Studio reader image reference mapping policy |
| `label_studio_writer_from_to_defaults` | Label Studio writer default `from_name` / `to_name` policy |
| `label_studio_writer_confidence_routing` | Label Studio writer routes confident annotations to predictions block |
| `labelbox_reader_id_assignment` | Labelbox reader deterministic ID assignment policy |
| `labelbox_reader_image_metadata` | Labelbox reader `data_row` / `media_attributes` mapping policy |
| `labelbox_writer_format_policy` | Labelbox writer chooses NDJSON for `.jsonl`/`.ndjson`, otherwise JSON array |
| `labelbox_writer_rectangle_policy` | Labelbox writer emits bbox-only `ImageBoundingBox` objects |
| `labelbox_writer_no_image_copy` | Labelbox writer does not copy image files |
| `scale_ai_reader_id_assignment` | Scale AI reader deterministic ID assignment policy |
| `scale_ai_reader_image_metadata` | Scale AI reader image reference and dimension resolution policy |
| `scale_ai_writer_deterministic_order` | Scale AI writer deterministic ordering policy |
| `scale_ai_writer_rectangle_policy` | Scale AI writer emits bbox-only `type: "box"` response annotations |
| `scale_ai_writer_no_image_copy` | Scale AI writer does not copy image files |
| `unity_perception_reader_id_assignment` | Unity Perception reader deterministic ID assignment policy |
| `unity_perception_reader_image_metadata` | Unity Perception reader capture/image metadata and dimension-resolution policy |
| `unity_perception_writer_directory_layout` | Unity Perception writer emits `annotation_definitions.json` plus `sequence.0/step*.frame_data.json` |
| `unity_perception_writer_rectangle_policy` | Unity Perception writer emits bbox-only `BoundingBox2D` values |
| `unity_perception_writer_no_image_copy` | Unity Perception writer does not copy image files |
| `cvat_reader_id_assignment` | CVAT reader deterministic ID assignment policy |
| `cvat_reader_attribute_policy` | CVAT reader coordinate + attribute mapping policy |
| `cvat_writer_meta_defaults` | CVAT writer minimal `<meta>` block policy |
| `cvat_writer_deterministic_order` | CVAT writer deterministic ordering (images by filename, boxes by annotation ID) |
| `cvat_writer_image_id_reassignment` | CVAT writer reassigns image IDs sequentially (original `cvat_image_id` not preserved) |
| `cvat_writer_source_default` | CVAT writer defaults missing `source` attribute to `manual` |
| `hf_reader_category_resolution` | HF reader category-name resolution precedence policy |
| `hf_reader_object_container_precedence` | HF reader selects object container: --hf-objects-column, then 'objects', then 'faces' |
| `hf_reader_bbox_format_dependence` | HF reader bbox interpretation depends on --hf-bbox-format flag |
| `hf_writer_deterministic_order` | HF writer deterministic metadata/annotation ordering policy |
| `sagemaker_reader_id_assignment` | SageMaker reader deterministic ID assignment policy |
| `sagemaker_reader_label_attribute_detection` | SageMaker reader detects one object-detection label attribute and rejects mixed/ambiguous manifests |
| `sagemaker_reader_class_map_resolution` | SageMaker reader resolves category names from class-map with numeric class_id fallback |
| `sagemaker_writer_deterministic_order` | SageMaker writer deterministic JSONL row and annotation ordering policy |
| `sagemaker_writer_class_map_policy` | SageMaker writer assigns class IDs by CategoryId order and emits class-map entries |
| `sagemaker_writer_metadata_defaults` | SageMaker writer deterministic label-attribute and metadata default policy |
| `sagemaker_writer_no_image_copy` | SageMaker writer does not copy image files |
| `labelme_reader_id_assignment` | LabelMe reader deterministic ID assignment policy |
| `labelme_reader_path_policy` | LabelMe reader file-name/path derivation policy |
| `labelme_polygon_envelope_applied` | LabelMe reader converted polygon shapes to axis-aligned bbox envelopes |
| `labelme_writer_file_layout` | LabelMe writer canonical annotations/ directory layout |
| `labelme_writer_rectangle_policy` | LabelMe writer emits all annotations as rectangle shapes |
| `labelme_writer_no_image_copy` | LabelMe writer does not copy image files |
| `superannotate_reader_id_assignment` | SuperAnnotate reader deterministic ID assignment policy |
| `superannotate_polygon_envelope_applied` | SuperAnnotate reader converted polygon/rotated geometries to axis-aligned bbox envelopes |
| `superannotate_writer_file_layout` | SuperAnnotate writer canonical annotations/ and classes/ directory layout |
| `superannotate_writer_rectangle_policy` | SuperAnnotate writer emits all annotations as bbox instances |
| `superannotate_writer_no_image_copy` | SuperAnnotate writer does not copy image files |
| `supervisely_reader_id_assignment` | Supervisely reader deterministic ID assignment policy |
| `supervisely_polygon_envelope_applied` | Supervisely reader converted polygon geometries to axis-aligned bbox envelopes |
| `supervisely_writer_project_layout` | Supervisely writer canonical project layout with meta.json and dataset/ann/ |
| `supervisely_writer_rectangle_policy` | Supervisely writer emits all annotations as rectangle objects |
| `supervisely_writer_no_image_copy` | Supervisely writer does not copy image files |
| `cityscapes_reader_id_assignment` | Cityscapes reader deterministic ID assignment policy |
| `cityscapes_polygon_envelope_applied` | Cityscapes reader converted polygons to axis-aligned bbox envelopes |
| `cityscapes_skipped_labels` | Cityscapes reader skips deleted objects plus ignored/stuff labels |
| `cityscapes_writer_gt_fine_layout` | Cityscapes writer canonical `gtFine/<split>/<city>/` layout |
| `cityscapes_writer_rectangle_polygon_policy` | Cityscapes writer emits bbox rectangles as four-point polygons |
| `cityscapes_writer_no_image_copy` | Cityscapes writer does not copy image files |
| `marmot_reader_id_assignment` | Marmot reader deterministic ID assignment policy |
| `marmot_reader_hex_coordinate_transform` | Marmot reader decodes CropBox/BBox hex doubles, scales through CropBox, and flips Y into pixel-space XYXY |
| `marmot_reader_companion_image_required` | Marmot reader requires same-stem companion images for dimensions |
| `marmot_writer_minimal_xml` | Marmot writer emits deterministic minimal Page/Composites/Composite XML |
| `marmot_writer_no_image_copy` | Marmot writer does not copy image files |
| `createml_reader_id_assignment` | CreateML reader deterministic ID assignment policy |
| `createml_reader_image_resolution` | CreateML reader image dimension resolution precedence |
| `createml_writer_deterministic_order` | CreateML writer deterministic ordering policy |
| `createml_writer_coordinate_mapping` | CreateML writer center-based coordinate mapping |
| `createml_writer_no_image_copy` | CreateML writer does not copy image files |
| `kitti_reader_id_assignment` | KITTI reader deterministic ID assignment policy |
| `kitti_reader_field_mapping` | KITTI reader maps non-bbox fields to kitti_* annotation attributes |
| `kitti_reader_image_resolution` | KITTI reader image dimension resolution from image_2/ |
| `kitti_writer_file_layout` | KITTI writer creates label_2/ with one .txt per image |
| `kitti_writer_default_field_values` | KITTI writer uses defaults for missing kitti_* attributes |
| `kitti_writer_deterministic_order` | KITTI writer deterministic ordering policy |
| `kitti_writer_no_image_copy` | KITTI writer does not copy image files |
| `via_reader_id_assignment` | VIA reader deterministic ID assignment policy |
| `via_reader_label_resolution` | VIA reader label resolution from region_attributes |
| `via_reader_image_resolution` | VIA reader image dimension resolution from disk |
| `via_writer_deterministic_order` | VIA writer deterministic ordering policy |
| `via_writer_label_attribute_key` | VIA writer canonical 'label' key in region_attributes |
| `via_writer_no_image_copy` | VIA writer does not copy image files |
| `retinanet_reader_id_assignment` | RetinaNet reader deterministic ID assignment policy |
| `retinanet_reader_image_resolution` | RetinaNet reader image dimension resolution from disk |
| `retinanet_reader_empty_row_handling` | RetinaNet reader empty-row handling for unannotated images |
| `retinanet_writer_deterministic_order` | RetinaNet writer deterministic ordering policy |
| `retinanet_writer_empty_rows` | RetinaNet writer empty-row convention for unannotated images |
| `retinanet_writer_no_image_copy` | RetinaNet writer does not copy image files |
| `openimages_reader_id_assignment` | OpenImages reader deterministic ID assignment policy |
| `openimages_reader_image_resolution` | OpenImages reader image dimension resolution from disk |
| `openimages_writer_deterministic_order` | OpenImages writer deterministic ordering policy |
| `kaggle_wheat_reader_id_assignment` | Kaggle Wheat reader deterministic ID assignment policy |
| `kaggle_wheat_writer_deterministic_order` | Kaggle Wheat writer deterministic ordering and bbox formatting |
| `automl_vision_reader_id_assignment` | AutoML Vision reader deterministic ID assignment policy |
| `automl_vision_reader_image_resolution` | AutoML Vision reader image dimension resolution from disk |
| `automl_vision_writer_deterministic_order` | AutoML Vision writer deterministic ordering policy |
| `udacity_reader_id_assignment` | Udacity reader deterministic ID assignment policy |
| `udacity_writer_row_order` | Udacity writer deterministic row ordering |
## Blocked conversions
When a conversion is blocked (lossy without `--allow-lossy`), panlabel still
emits the full conversion report to **stdout** before printing the blocking
error to **stderr** and exiting non-zero. This means:
- **Text mode** (default): the report appears on stdout with stable codes in
brackets (e.g. `[drop_dataset_info]`), then the error on stderr.
- **`--report json`**: stdout contains the full JSON report (parseable by
downstream tools), stderr contains the concise blocking error.
This lets you inspect exactly what would change before deciding to use
`--allow-lossy`.
## Practical guidance
- Blocked conversions print the full report to stdout — review it to understand
which warnings triggered the block.
- Use `--report json` for machine-readable output, even on blocked conversions.
- Prefer explicit `--allow-lossy` only when you accept those specific losses.
### Issue-code entries for the eight bbox-only adapters
These stable codes are currently emitted by the static-image bbox-only adapters:
- `datumaro_reader_id_assignment`
- `datumaro_writer_deterministic_order`
- `wider_face_reader_id_assignment`
- `wider_face_writer_file_layout`
- `oidv4_reader_id_assignment`
- `oidv4_writer_file_layout`
- `bdd100k_reader_id_assignment`
- `bdd100k_writer_deterministic_order`
- `v7_darwin_reader_id_assignment`
- `v7_darwin_writer_deterministic_order`
- `edge_impulse_reader_id_assignment`
- `edge_impulse_writer_deterministic_order`
- `openlabel_reader_id_assignment`
- `openlabel_writer_frame_layout`
- `via_csv_reader_id_assignment`
- `via_csv_writer_deterministic_order`
Related implementation counters in dataset metadata (set by readers when richer structures are skipped):
- `datumaro_unsupported_annotations_skipped`
- `bdd100k_unsupported_labels_skipped`
- `darwin_unsupported_annotations_skipped`
- `openlabel_unsupported_data_skipped`
- `via_csv_non_rect_regions_skipped`