ADV-FORMS

# Overview ## Top-level structure Each top-level item represents a single image task and includes: - `data`: image metadata, including the `image` path. - `annotations`: a list of annotation records. - `created_at`: task creation timestamp. - `updated_at`: task update timestamp. - `total_annotations`: number of annotation records. Example: ```json { "data": { "image": "ADV-FORMS_images/q003_003_1881_R.jpg" }, "annotations": [ { "id": 86, "completed_by": 3, "result": [ ... ] } ], "created_at": "2026-06-23T07:45:00Z", "updated_at": "2026-06-23T07:45:00Z", "total_annotations": 1 } ``` ## `annotations` Each `annotations` entry contains a `result` array with multiple Label Studio result items. In this dataset, the two primary item types are `rectanglelabels` and `textarea`, which typically appear together for the same labeled region. ### `rectanglelabels` `rectanglelabels` results define labeled bounding boxes on the image. A typical `rectanglelabels` item looks like: ```json { "id": "2726ba22-eec2-4121-bcda-8b592b6d7cda", "type": "rectanglelabels", "from_name": "label", "to_name": "image", "value": { "x": 47.67, "y": 3.20, "width": 7.37, "height": 5.95, "rotation": 0, "rectanglelabels": ["location_ID_part1"] } } ``` Important `value` fields: - `x`, `y`: top-left corner coordinates as percentages of the image size. - `width`, `height`: box size as percentages of the image dimensions. - `rotation`: box rotation, usually `0`. - `rectanglelabels`: class label array for the region. `rectanglelabels` entries identify where on the image a labeled field appears and what label category it belongs to. ### `textarea` `textarea` results contain transcribed text for a labeled region. A typical `textarea` item looks like: ```json { "id": "2726ba22-eec2-4121-bcda-8b592b6d7cda", "type": "textarea", "from_name": "transcription", "to_name": "image", "value": { "text": ["153"], "x": 47.67, "y": 3.20, "width": 7.37, "height": 5.95, "rotation": 0 } } ``` Important `value` fields: - `text`: array of transcribed strings. - `x`, `y`, `width`, `height`: optional geometry, often matching the related `rectanglelabels` box. `textarea` entries capture the transcribed text content for each labeled region. ## How `rectanglelabels` and `textarea` work together In this dataset, annotation results are often paired by the same `id` value: - `rectanglelabels` marks the labeled region and class. - `textarea` provides the text transcription for that same region. Pairing by `id` allows to combine region labels with transcription content. ## Notes for users - Coordinates are expressed as percentages, not pixels. - Use `original_width` and `original_height` when converting relative coordinates to absolute pixels. - Annotation records may include other Label Studio metadata, but `rectanglelabels` and `textarea` are the primary fields for extraction. ## Purpose This README is intended for users who need to: - understand the cleaned Label Studio schema used by `ADV-FORMS_ls.json` - extract bounding boxes and transcriptions - convert annotations to other formats (PAGE XML, COCO, VOC, etc.) ## Direct Label Studio Import The JSON-schema of the dataset can be directly imported into label studio. Users only need to adjust the image paths in the JSON according to their specific Label Studio setup and copy the labeling interface template given below into their Label Studio project. ### Adapting image paths for your Label Studio setup The `data.image` field in this JSON contains `ADV-FORMS_images/<filename>.jpg`. When importing the data into Label Studio, **you must adjust this path to match your concrete Label Studio setup**. Label Studio supports multiple storage backends. Depending on how your Label Studio instance is configured, you may need to: - **Local file storage**: use relative or absolute filesystem paths. - **S3 or cloud storage**: use URLs (e.g., `https://s3.example.com/bucket/...`). - **Label Studio's local files**: use the special `/data/local-files/?d=path` format. **Example adjustments**: - Original: `ADV-FORMS_images/q003_003_1881_R.jpg` - For S3: `https://my-bucket.s3.amazonaws.com/ADV-FORMS_images/q003_003_1881_R.jpg` - For Label Studio local files: `/data/local-files/?d=ADV-FORMS/images/q003_003_1881_R.jpg` - For absolute filesystem path: `/home/user/data/ADV-FORMS_images/q003_003_1881_R.jpg` Before importing, adjust all `data.image` paths in your JSON to match your storage setup. ### Labeling interface template Use the following Label Studio task template to set up the labeling interface: <View> <View style="display:flex;align-items:start;gap:8px;flex-direction:row-reverse"> <Image name="image" value="$image" zoom="true" zoomControl="true"/> <View> <RectangleLabels name="label" toName="image" showInline="false"> <Label value="location_ID_part1" category="1" background="#a09af9"/> <Label value="location_ID_part2" category="2" background="#ff0000"/> <Label value="location_ID_part3" category="3" background="#FFC069"/> <Label value="location_ID_full" category="0" background="#808080"/> <Label value="location_region_ID" category="4" background="#2eff3c"/> <Label value="answer_handwritten" category="5" background="#4bfa00"/> <Label value="answer_typewritten" category="6" background="#d6009d"/> <Label value="answer_multiline_container" category="7" background="#007bff"/> <Label value="mark_quote" category="8" background="#f50000"/> <Label value="mark_omission" category="9" background="#cda3ff"/> <Label value="mark_cross_out" category="10" background="#1d6010"/> <Label value="mark_underline" category="11" background="#f1ff29"/> <Label value="mark_selection" category="12" background="#216673"/> <Label value="mark_curly_bracket" category="13" background="#64f7f4"/> <Label value="mark_drawing" category="14" background="#816c31"/> <Label value="pre-print" category="15" background="#000000"/> <Label value="pre-print-drawing" category="16" background="#832a2a"/> </RectangleLabels> <View visibleWhen="region-selected" whenLabelValue="location_ID_part1,location_ID_part2,location_ID_part3,location_ID_full,location_region_ID,answer_handwritten,answer_typewritten,pre-print,pre-print-drawing"> <TextArea name="transcription" toName="image" editable="true" perRegion="true" required="true" maxSubmissions="1" rows="5" placeholder="Recognized Text" displayMode="region-list" perRegionVisible="true" whenTagName="label" strokeWidth="1" whenLabelValue="location_ID_part1,location_ID_part2,location_ID_part3,location_ID_full,location_region_ID,answer_handwritten,answer_typewritten,pre-print"/> </View> </View> </View> </View> ``` ## References For more information on Label Studio and annotation workflows, refer to: - **Importing Annotations**: [Label Studio — Import Predictions and Annotations](https://labelstud.io/guide/predictions.html) — Learn how to import pre-existing annotations into a Label Studio project. - **Defining Labeling Interface**: [Label Studio — Labeling Configuration](https://labelstud.io/guide/setup.html) — Reference for creating custom task templates with XML-based labeling controls. - **Image Configuration**: [Label Studio — Image Control](https://labelstud.io/guide/images.html) — Details on configuring image display and storage in Label Studio tasks. - **Bounding Boxes**: [Label Studio — Rectangle Labels](https://labelstud.io/guide/rectangle-labels.html) — Documentation on `RectangleLabels` for region annotation. - **Text Areas**: [Label Studio — Text Areas](https://labelstud.io/guide/text-area.html) — Reference for text transcription and input controls.