`utilities.read_file` raises `KeyError: 'segmentation'` when loading valid COCO bbox annotations with `segmentation`

[kiplimock]

Describe the bug
When using deepforest.utilities.read_file (DeepForest 2.0.0) to load a valid COCO detection JSON (bbox-only, no segmentation), the function raises a KeyError: 'segmentation'.

The JSON follows standard COCO detection format:

• Top-level keys: info, licenses, images, annotations, categories
• Each annotation has: id, image_id, category_id, bbox, area, iscrowd
• No segmentation field (which is optional in COCO when you only use bounding boxes)

However, internally utilities.read_file assumes that a segmentation key is always present in each annotation and fails with KeyError when it is not.

This makes it impossible to directly use standard COCO detection datasets with DeepForest via utilities.read_file without first modifying the COCO file.

To Reproduce

1. Create a minimal COCO JSON file (e.g., annotations.json) with:

• One image:

     "images": [
       {
         "id": 1,
         "file_name": "2024_08_1.tif",
         "height": 4325,
         "width": 4325
       }
     ]

• One bbox-only annotation (no segmentation key):

     "annotations": [
       {
         "id": 1,
         "image_id": 1,
         "category_id": 1,
         "bbox": [1364.38, 1586.75, 115.60, 119.88],
         "area": 13859.10,
         "iscrowd": 0
       }
     ]

• One category:

     "categories": [
       {
         "id": 1,
         "name": "tree",
         "supercategory": "object"
       }
     ]

2. In a notebook or script

   from deepforest import utilities

   root_dir = r"some_directory"
   annotations_file = "annotations.json"

   annotations = utilities.read_file(annotations_file, root_dir=root_dir)

3. Observe that utilities.read_file raises:

Environment:

• OS: Windows 11 Home 64-bit (10.0, Build 26200)
• Python version and environment: 3.12
• DeepForest: Version 2.0.0
• Installation: Conda, version 24.11.1

Screenshots and Context

User Story
As a researcher working with aerial tree detection datasets using standard COCO bbox annotations, I want to load my existing COCO JSON files directly with deepforest.utilities.read_file (or an equivalent DeepForest loader) without having to modify them, so that I can quickly plug DeepForest into my existing COCO-labelled workflows and tools without adding custom pre-processing steps or deviating from the COCO standard.

[jveitchmichaelis]

I was looking through the read_coco function and it looks like we should support this, but we don't check for the bbox key at all. Our read_coco function is targeted towards polygon datasets as we (currently) expect users to provide annotations in CSV format.

DeepForest/src/deepforest/utilities.py

Lines 442 to 450 in cc6b174

	for annotation in coco_data["annotations"]:
	segmentation = annotation.get("segmentation")
	if not segmentation:
	continue
	# COCO polygons are usually a list of lists; take the first (assume "single part")
	segmentation_mask = segmentation[0]
	# Convert flat list to coordinate pairs
	pairs = [
	(segmentation_mask[i], segmentation_mask[i + 1])

I'll add this - should be straightforward.

[jveitchmichaelis]

I've submitted a small PR for this. It does relate to some future work because:

• We will probably want to be able to choose between formats (e.g. box vs segmentation vs keypoint) as it's not always desirable to default to polygons.
• I suggested adding a task field to read_coco to support this. Longer term I'm envisioning that we have a task key in the config which will propagate to ensure that we create the right kinds of dataloaders and models.
• csv_file is a bit overloaded and at some point we could consider replacing with label_file or something like that.

@kiplimock out of interest are you trying to train a model, or use your own dataset for evaluation?

[kiplimock]

@jveitchmichaelis, my installation is version 2.0.0, which is the latest release I can see on PyPi. I think the update you referred to is a recent commit in a version you haven't released yet.

Thanks for noting that this need attention.

I am attempting to finetune the tree detection model using a dataset that we are working on releasing soon.

[kiplimock]

I was working with version 1.5.2 and was planning to write my own code to read the COCO json files, but chose not to when I noticed that 2.0.0 has a helper method for that. Of course I'm back to creating my own workaround now. The dataset I am using is our lab's inhouse dataset that we are currently getting ready for release. Thanks!

…

--- Regards, Cedric Kiplimo

On Sun, 25 Jan 2026 at 00:24, Josh Veitch-Michaelis < ***@***.***> wrote: *jveitchmichaelis* left a comment (weecology/DeepForest#1281) <#1281 (comment)> You're correct that we currently don't support MS-COCO directly. This is mainly because until now, we haven't needed to - we use a very simple format similar to YOLO (image, label, 4 coordinates). Out of interest, which dataset are you working with? This is on the roadmap and should be added when we begin to support additional output tasks. Tagged myself. — Reply to this email directly, view it on GitHub <#1281 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ALEBIPWG5WVWDFXQVM3QBG34IPPJVAVCNFSM6AAAAACSUVO57CVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOOJVGUZDSNJRGI> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[jveitchmichaelis]

My mistake when I saw the issue. There was a recent change to prevent read_coco from throwing an error if the segmentation key is missing, so the particular error you're seeing should be fixed. However, then I noticed we don't actually load bbox labels at all through this method, so your request is still a todo.

This is a slightly larger change than I anticipated as we need to determine when to load polygons vs boxes, as all coco polygon datasets have both.

In the meantime, the CSV format we use is easy to convert to, so I'd suggest using that rather than waiting for a new release. Short term, perhaps we can add a small utility script to convert the labels instead?

[kiplimock]

No problem. I already wrote my own script to create a CSV out of the JSON annotations. So I am good to go for now.

[tangelll]

Is this issue still in progress or is it already closed?

[jveitchmichaelis]

This is still open and will be integrated into newer dataloaders that we’re working on for keypoint and polygon annotations. Thanks!