label-studio-sdk 1.0.20__py3-none-any.whl → 2.0.1__py3-none-any.whl

label_studio_sdk/converter/README.md

@@ -425,6 +425,213 @@ e.g.:
 - The Local Storage in Label Studio is set up correctly with the Absolute local path to your images (`/yolo/datasets/one/images`)
 - For more details, refer to the documentation on [importing pre-annotated data](https://labelstud.io/guide/predictions.html) and [setting up Cloud Storages](https://labelstud.io/guide/storage).
 
+# COCO to Label Studio Converter 
+
+### COCO dataset structure
+
+Check the structure of COCO dataset first. The typical COCO dataset structure:
+
+```
+/coco/dataset
+  annotations/
+   - instances_train2017.json
+   - instances_val2017.json
+   - person_keypoints_train2017.json
+   - (other annotation files...)
+  train2017/
+   - 000000000139.jpg
+   - 000000000285.jpg
+   - ...
+  val2017/
+   - 000000000139.jpg
+   - 000000000285.jpg
+   - ...
+```
+
+*COCO JSON annotation file structure*
+
+```json
+{
+  "images": [
+    {
+      "id": 139,
+      "width": 426,
+      "height": 640,
+      "file_name": "000000000139.jpg"
+    }
+  ],
+  "annotations": [
+    {
+      "id": 1768,
+      "image_id": 139,
+      "category_id": 64,
+      "bbox": [412.8, 157.61, 11.65, 12.64],
+      "area": 147.24,
+      "iscrowd": 0,
+      "segmentation": [[...]]
+    }
+  ],
+  "categories": [
+    {
+      "id": 1,
+      "name": "person",
+      "supercategory": "person"
+    }
+  ]
+}
+```
+
+### Usage
+
+```
+label-studio-converter import coco -i /coco/dataset/annotations/instances_val2017.json -o ls-tasks.json --image-root-url "/data/local-files/?d=val2017"
+```
+Where the URL path from `?d=` is relative to the path you set in `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT`.
+
+**Note for Local Storages** 
+  * It's very important to set `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/coco/dataset` (**not** to `/coco/dataset/val2017`, but **`/coco/dataset`**) for Label Studio to run.
+  * [Add a new Local Storage](https://labelstud.io/guide/storage#Local-storage) in the project settings and set **Absolute local path** to `/coco/dataset/val2017` (or `c:\coco\dataset\val2017` for Windows). 
+
+**Note for Cloud Storages**
+  * Use `--image-root-url` to make correct prefixes for task URLs, e.g. `--image-root-url s3://my-bucket/coco/val2017/`.
+  * [Add a new Cloud Storage](https://labelstud.io/guide/storage) in the project settings with the corresponding bucket and prefix.
+
+**Additional Options**
+  * Use `--use-super-categories` to include COCO super categories in label names (e.g., "vehicle:car" instead of "car")
+  * Use `--out-type predictions` to import as predictions instead of ground truth annotations
+  * Use `--point-width 2.0` to adjust keypoint size for pose estimation tasks
+
+**Help command**
+
+```
+label-studio-converter import coco -h
+
+usage: label-studio-converter import coco [-h] -i INPUT [-o OUTPUT]
+                                          [--to-name TO_NAME]
+                                          [--from-name FROM_NAME]
+                                          [--out-type OUT_TYPE]
+                                          [--image-root-url IMAGE_ROOT_URL]
+                                          [--point-width POINT_WIDTH]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -i INPUT, --input INPUT
+                        input COCO json file
+  -o OUTPUT, --output OUTPUT
+                        output file with Label Studio JSON tasks
+  --to-name TO_NAME     object name from Label Studio labeling config
+  --from-name FROM_NAME
+                        control tag name from Label Studio labeling config
+  --out-type OUT_TYPE   annotation type - "annotations" or "predictions"
+  --image-root-url IMAGE_ROOT_URL
+                        root URL path where images will be hosted, e.g.:
+                        http://example.com/images or s3://my-bucket
+  --point-width POINT_WIDTH
+                        key point width (size)
+```
+
+## Tutorial: Importing COCO Pre-Annotated Images to Label Studio using Local Storage
+
+This tutorial will guide you through the process of importing a COCO dataset into Label Studio for further annotation or review. 
+We'll cover setting up your environment, converting COCO annotations to Label Studio's format, and importing them into your project.
+
+### Prerequisites
+- Label Studio installed locally
+- COCO dataset with JSON annotation file and images in the directory `/coco/dataset`.
+- Label Studio SDK installed (available via `pip install label-studio-sdk`) -- this includes the `label-studio-converter` tool that you will use
+
+### Step 1: Set Up Your Environment and Run Label Studio
+Before starting Label Studio, set the following environment variables to enable Local Storage file serving:
+
+Unix systems: 
+```
+export LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true
+export LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/coco/dataset
+label-studio
+```
+
+Windows: 
+```
+set LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true
+set LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=C:\\coco\\dataset
+label-studio
+```
+
+Replace `/coco/dataset` with the actual path to your COCO dataset directory.
+
+### Step 2: Setup Local Storage
+1. Create a new project.
+2. Go to the project settings and select **Cloud Storage**. 
+3. Click **Add Source Storage** and select **Local files** from the **Storage Type** options.  
+4. Set the **Absolute local path** to `/coco/dataset/val2017` (or your image folder path, e.g., `c:\coco\dataset\val2017` on Windows).
+5. Click `Add storage`.
+
+Check more details about Local Storages [in the documentation](https://labelstud.io/guide/storage.html#Local-storage).
+
+### Step 3: Verify Image Access
+Before importing the converted annotations from COCO, verify that you can access an image from your Local storage via Label Studio. Open a new browser tab and enter the following URL:
+
+```
+http://localhost:8080/data/local-files/?d=val2017/000000000139.jpg
+```
+
+Replace `val2017/000000000139.jpg` with the path to one of your images. The image should display **in the new tab of the browser**.
+If you can't open an image, the Local Storage configuration is incorrect. The most likely reason is that you made a mistake when specifying your `Path` in Local Storage settings or in `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT`. 
+
+**Note:** The URL path from `?d=` should be relative to `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/coco/dataset`, 
+it means that the real path will be `/coco/dataset/val2017/000000000139.jpg` and this image should exist on your hard drive.
+
+### Step 4: Convert COCO Annotations
+Use the label-studio-converter to convert your COCO annotations to a format that Label Studio can understand:
+
+```
+label-studio-converter import coco -i /coco/dataset/annotations/instances_val2017.json -o output.json --image-root-url "/data/local-files/?d=val2017/"
+```
+
+**For different annotation types:**
+- **Object Detection (bounding boxes)**: Use `instances_*.json` files
+- **Instance Segmentation**: Use `instances_*.json` files (includes both bboxes and polygon segmentations)  
+- **Keypoint Detection (pose estimation)**: Use `person_keypoints_*.json` files
+- **With super categories**: Add `--use-super-categories` flag
+
+### Step 5: Import Converted Annotations
+Now import the `output.json` file into Label Studio:
+1. Go to your Label Studio project.
+2. From the Data Manager, click **Import**.
+3. Select the `output.json` file and import it.
+4. If a label configuration file was generated (e.g., `output.label_config.xml`), you can use it in your project settings under **Labeling Interface**.
+
+### Step 6: Verify Annotations
+After importing, you should see your images with the pre-annotated bounding boxes, segmentations, or keypoints in Label Studio. Verify that the annotations are correct and make any necessary adjustments.
+
+### Annotation Type Support
+The COCO converter supports (see more details and examples here: https://labelstud.io/guide/export.html#COCO):
+- ✅ **Bounding boxes** (object detection)
+- ✅ **Polygon segmentations** (instance segmentation) - experimental
+- ✅ **Keypoint detection** (pose estimation) - without skeleton connections
+- ❌ **RLE segmentations** - not yet supported
+
+### Troubleshooting
+If you encounter issues with paths or image access, ensure that:
+- The LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT is set correctly.
+- The `--image-root-url` in the conversion command matches the relative path:
+```
+`Absolute local path from Local Storage Settings` - `LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT` = `path for --image_root_url`
+```
+e.g.:
+```
+/coco/dataset/val2017 - /coco/dataset/ = val2017/
+```
+- The Local Storage in Label Studio is set up correctly with the Absolute local path to your images (`/coco/dataset/val2017`)
+- Your COCO JSON file is valid and contains the expected structure
+- Image file names in the COCO JSON match the actual files in your images directory
+- For more details, refer to the documentation on [importing pre-annotated data](https://labelstud.io/guide/predictions.html) and [setting up Cloud Storages](https://labelstud.io/guide/storage).
+
+**Common Issues:**
+- **"No labels converted"**: Check that your COCO JSON file contains annotations and that image files exist
+- **Images not loading**: Verify the image paths and Local Storage configuration
+- **Missing annotations**: Ensure the image IDs in the COCO JSON match the imported images
+
 ------------
 
 # Contributing

label_studio_sdk/converter/imports/coco.py

@@ -11,6 +11,16 @@ logger = logging.getLogger("root")
 
 
 def new_task(out_type, root_url, file_name):
+    """Create a new Label Studio task structure.
+    
+    Args:
+        out_type (str): Type of output - either 'annotations' or 'predictions'
+        root_url (str): Root URL path where images will be hosted
+        file_name (str): Name of the image file
+        
+    Returns:
+        dict: Label Studio task structure with image data and empty result array
+    """
     return {
         "data": {"image": os.path.join(root_url, file_name)},
         # 'annotations' or 'predictions'
@@ -24,9 +34,27 @@ def new_task(out_type, root_url, file_name):
 
 
 def create_bbox(annotation, categories, from_name, image_height, image_width, to_name):
+    """Convert COCO bounding box annotation to Label Studio format.
+    
+    COCO bbox format: [x, y, width, height] where (x,y) is top-left corner
+    Label Studio format: percentages relative to image dimensions
+    
+    Args:
+        annotation (dict): COCO annotation containing bbox and category_id
+        categories (dict): Mapping of category_id to category name
+        from_name (str): Control tag name from Label Studio labeling config
+        image_height (int): Height of the source image in pixels
+        image_width (int): Width of the source image in pixels
+        to_name (str): Object name from Label Studio labeling config
+        
+    Returns:
+        dict: Label Studio rectangle annotation item
+    """
     label = categories[int(annotation["category_id"])]
     x, y, width, height = annotation["bbox"]
     x, y, width, height = float(x), float(y), float(width), float(height)
+    
+    # Convert absolute coordinates to percentages
     item = {
         "id": uuid.uuid4().hex[0:10],
         "type": "rectanglelabels",
@@ -50,9 +78,28 @@ def create_bbox(annotation, categories, from_name, image_height, image_width, to
 def create_segmentation(
     category_id, segmentation, categories, from_name, image_height, image_width, to_name
 ):
+    """Convert COCO segmentation annotation to Label Studio polygon format.
+    
+    COCO segmentation format: flat array of [x1,y1,x2,y2,...] coordinates
+    Label Studio format: array of [x,y] points as percentages
+    
+    Args:
+        category_id (int): COCO category ID for this segmentation
+        segmentation (list): Flat list of polygon coordinates [x1,y1,x2,y2,...]
+        categories (dict): Mapping of category_id to category name
+        from_name (str): Control tag name from Label Studio labeling config
+        image_height (int): Height of the source image in pixels
+        image_width (int): Width of the source image in pixels
+        to_name (str): Object name from Label Studio labeling config
+        
+    Returns:
+        dict: Label Studio polygon annotation item
+    """
     label = categories[int(category_id)]
+    # Convert flat array [x1,y1,x2,y2,...] to array of points [[x1,y1],[x2,y2],...]
     points = [list(x) for x in zip(*[iter(segmentation)] * 2)]
 
+    # Convert absolute coordinates to percentages
     for i in range(len(points)):
         points[i][0] = points[i][0] / image_width * 100.0
         points[i][1] = points[i][1] / image_height * 100.0
@@ -73,13 +120,33 @@ def create_segmentation(
 def create_keypoints(
     annotation, categories, from_name, to_name, image_height, image_width, point_width
 ):
+    """Convert COCO keypoints annotation to Label Studio keypoint format.
+    
+    COCO keypoints format: [x1,y1,v1,x2,y2,v2,...] where v is visibility flag
+    v=0: not labeled, v=1: labeled but not visible, v=2: labeled and visible
+    
+    Args:
+        annotation (dict): COCO annotation containing keypoints and category_id
+        categories (dict): Mapping of category_id to category name
+        from_name (str): Control tag name from Label Studio labeling config
+        to_name (str): Object name from Label Studio labeling config
+        image_height (int): Height of the source image in pixels
+        image_width (int): Width of the source image in pixels
+        point_width (float): Width/size of keypoints in Label Studio
+        
+    Returns:
+        list: List of Label Studio keypoint annotation items
+    """
     label = categories[int(annotation["category_id"])]
     points = annotation["keypoints"]
     items = []
 
+    # Process keypoints in groups of 3: x, y, visibility
     for i in range(0, len(points), 3):
         x, y, v = points[i : i + 3]  # x, y, visibility
         x, y, v = float(x), float(y), int(v)
+        
+        # Convert absolute coordinates to percentages
         item = {
             "id": uuid.uuid4().hex[0:10],
             "type": "keypointlabels",
@@ -96,7 +163,7 @@ def create_keypoints(
             "original_height": image_height,
         }
 
-        # visibility
+        # Handle visibility: if v < 2, the keypoint is hidden
         if v < 2:
             item["value"]["hidden"] = True
 
@@ -114,49 +181,78 @@ def convert_coco_to_ls(
     use_super_categories=False,
     point_width=1.0,
 ):
-    """Convert COCO labeling to Label Studio JSON
-
-    :param input_file: file with COCO json
-    :param out_file: output file with Label Studio JSON tasks
-    :param to_name: object name from Label Studio labeling config
-    :param from_name: control tag name from Label Studio labeling config
-    :param out_type: annotation type - "annotations" or "predictions"
-    :param image_root_url: root URL path where images will be hosted, e.g.: http://example.com/images
-    :param use_super_categories: use super categories from categories if they are presented
-    :param point_width: key point width
+    """Convert COCO dataset annotations to Label Studio JSON format.
+    
+    This function processes a COCO dataset JSON file and converts all annotations
+    (bounding boxes, segmentations, keypoints) to Label Studio's format. It supports:
+    - Object detection (bounding boxes)
+    - Instance segmentation (polygons) 
+    - Keypoint detection (pose estimation)
+    
+    The function automatically generates a Label Studio labeling configuration
+    based on the annotation types found in the COCO dataset.
+
+    Args:
+        input_file (str): Path to input COCO JSON file
+        out_file (str): Path to output Label Studio JSON file
+        to_name (str, optional): Object name from Label Studio labeling config. Defaults to "image".
+        from_name (str, optional): Control tag name from Label Studio labeling config. Defaults to "label".
+        out_type (str, optional): Annotation type - "annotations" or "predictions". Defaults to "annotations".
+        image_root_url (str, optional): Root URL path where images will be hosted. 
+            Defaults to "/data/local-files/?d=" for local storage.
+        use_super_categories (bool, optional): Use super categories from COCO if available. Defaults to False.
+        point_width (float, optional): Width/size of keypoints in pixels. Defaults to 1.0.
+    
+    Example:
+        >>> convert_coco_to_ls(
+        ...     input_file='annotations/instances_val2017.json',
+        ...     out_file='label_studio_tasks.json',
+        ...     image_root_url='s3://my-bucket/images/',
+        ...     use_super_categories=True
+        ... )
+        
+    Note:
+        - The function will create a corresponding .label_config.xml file with the labeling configuration
+        - RLE (Run-Length Encoding) segmentations are not yet supported
+        - Keypoints are supported without skeleton connections
+        - Images must be accessible at the specified image_root_url
     """
 
     tasks = {}  # image_id => task
     logger.info("Reading COCO notes and categories from %s", input_file)
 
+    # Load and parse COCO JSON file
     with open(input_file, encoding="utf8") as f:
         coco = json.load(f)
 
-    # build categories => labels dict
+    # Build categories => labels dict
     new_categories = {}
-    # list to dict conversion: [...] => {category_id: category_item}
+    # Convert list to dict: [...] => {category_id: category_item}
     categories = {int(category["id"]): category for category in coco["categories"]}
-    ids = sorted(categories.keys())  # sort labels by their origin ids
+    ids = sorted(categories.keys())  # Sort labels by their original IDs
 
+    # Build category name mapping, optionally including super categories
     for i in ids:
         name = categories[i]["name"]
         if use_super_categories and "supercategory" in categories[i]:
             name = categories[i]["supercategory"] + ":" + name
         new_categories[i] = name
 
-    # mapping: id => category name
+    # Final mapping: id => category name
     categories = new_categories
 
-    # mapping: image id => image
+    # Create mapping: image id => image metadata
     images = {item["id"]: item for item in coco["images"]}
 
     logger.info(
         f'Found {len(categories)} categories, {len(images)} images and {len(coco["annotations"])} annotations'
     )
 
-    # flags for labeling config composing
+    # Flags for tracking annotation types and generating appropriate labeling config
     segmentation = bbox = keypoints = rle = False
     segmentation_once = bbox_once = keypoints_once = rle_once = False
+    
+    # Generate appropriate from_name tags for different annotation types
     rectangles_from_name, keypoints_from_name = (
         from_name + "_rectangles",
         from_name + "_keypoints",
@@ -164,27 +260,30 @@ def convert_coco_to_ls(
     segmentation_from_name = from_name + "polygons"
     tags = {}
 
-    # create tasks
+    # Create initial tasks for each image
     for image in coco["images"]:
         image_id, image_file_name = image["id"], image["file_name"]
         tasks[image_id] = new_task(out_type, image_root_url, image_file_name)
 
+    # Process all annotations
     for i, annotation in enumerate(coco["annotations"]):
+        # Detect which annotation types are present
         segmentation |= "segmentation" in annotation
         bbox |= "bbox" in annotation
         keypoints |= "keypoints" in annotation
         rle |= (
             annotation.get("iscrowd") == 1
-        )  # 0 - polygons are in segmentation, otherwise rle
+        )  # 0 - polygons are in segmentation, otherwise RLE
 
-        if rle and not rle_once:  # not supported
+        # Log warnings and build tag configuration
+        if rle and not rle_once:  # RLE not supported yet
             logger.error("RLE in segmentation is not yet supported in COCO")
             rle_once = True
         if keypoints and not keypoints_once:
             logger.warning("Keypoints are partially supported without skeletons")
             tags.update({keypoints_from_name: "KeyPointLabels"})
             keypoints_once = True
-        if segmentation and not segmentation_once:  # not supported
+        if segmentation and not segmentation_once:  # Experimental support
             logger.warning("Segmentation in COCO is experimental")
             tags.update({segmentation_from_name: "PolygonLabels"})
             segmentation_once = True
@@ -192,7 +291,7 @@ def convert_coco_to_ls(
             tags.update({rectangles_from_name: "RectangleLabels"})
             bbox_once = True
 
-        # read image sizes
+        # Get image metadata for coordinate conversion
         image_id = annotation["image_id"]
         image = images[image_id]
         image_file_name, image_width, image_height = (
@@ -203,6 +302,7 @@ def convert_coco_to_ls(
 
         task = tasks[image_id]
 
+        # Convert bounding box annotations
         if "bbox" in annotation:
             item = create_bbox(
                 annotation,
@@ -214,6 +314,7 @@ def convert_coco_to_ls(
             )
             task[out_type][0]["result"].append(item)
 
+        # Convert segmentation annotations (polygons)
         if "segmentation" in annotation and len(annotation["segmentation"]):
             for single_segmentation in annotation["segmentation"]:
                 item = create_segmentation(
@@ -227,6 +328,7 @@ def convert_coco_to_ls(
                 )
                 task[out_type][0]["result"].append(item)
 
+        # Convert keypoint annotations
         if "keypoints" in annotation:
             items = create_keypoints(
                 annotation,
@@ -241,16 +343,18 @@ def convert_coco_to_ls(
 
         tasks[image_id] = task
 
-    # generate and save labeling config
+    # Generate and save labeling configuration
     label_config_file = out_file.replace(".json", "") + ".label_config.xml"
     generate_label_config(categories, tags, to_name, from_name, label_config_file)
 
+    # Save converted tasks to output file
     if len(tasks) > 0:
         tasks = [tasks[key] for key in sorted(tasks.keys())]
         logger.info("Saving Label Studio JSON to %s", out_file)
         with open(out_file, "w") as out:
             json.dump(tasks, out)
 
+        # Print helpful instructions for user
         print(
             "\n"
             f"  1. Create a new project in Label Studio\n"
@@ -264,6 +368,11 @@ def convert_coco_to_ls(
 
 
 def add_parser(subparsers):
+    """Add COCO converter arguments to command line parser.
+    
+    Args:
+        subparsers: Argparse subparsers object to add the COCO parser to
+    """
     coco = subparsers.add_parser("coco")
 
     coco.add_argument(

label_studio_sdk/core/__init__.py

@@ -20,6 +20,7 @@ from .query_encoder import encode_query
 from .remove_none_from_dict import remove_none_from_dict
 from .request_options import RequestOptions
 from .serialization import FieldMetadata, convert_and_respect_annotation_metadata
+from .unchecked_base_model import UncheckedBaseModel, UnionMetadata, construct_type
 
 __all__ = [
     "ApiError",
@@ -34,8 +35,11 @@ __all__ = [
     "RequestOptions",
     "SyncClientWrapper",
     "SyncPager",
+    "UncheckedBaseModel",
+    "UnionMetadata",
     "UniversalBaseModel",
     "UniversalRootModel",
+    "construct_type",
     "convert_and_respect_annotation_metadata",
     "convert_file_dict_to_httpx_tuples",
     "encode_query",