Instances & identity

1. Motivation¶

Every function you use later in this lesson, training, inference, evaluation, works on the assumption that “field number 7” is meaningfully different from “field number 12,” even though both are simply “field” as a class. Understanding this distinction now makes the rest of the lesson, especially reading raw prediction output, far less confusing.

2. Core idea¶

A semantic segmentation label answers “what class is this pixel,” using one value per class. An instance segmentation label answers “what class, and which specific object,” using one value per object. Two adjacent fields of the same crop still get two different values, because the label encodes object identity, not just class membership.

Take the field-parcel example directly: a semantic segmentation model applied to a farming region might produce one large connected region labeled “field.” From that output alone, you cannot tell whether it contains 5 parcels or 50, and you cannot compute the area of any individual one. An instance segmentation model instead produces a separate mask per parcel, each with its own instance identifier and confidence score, which is what makes counting, per-parcel measurement, and tracking possible.

3. How instance identity is represented¶

A. Class labels and instance IDs¶

Consider three neighboring fields.

A semantic class raster might contain:

0 0 0 0 0 0
0 1 1 1 1 0
0 1 1 1 1 0
0 0 0 0 0 0

where:

0 = background
1 = field

This tells us which pixels are fields, but not how many fields exist.

An instance raster could instead contain:

0 0 0 0 0 0 0
0 1 1 2 2 3 0
0 1 1 2 2 3 0
0 1 1 2 2 3 0
0 0 0 0 0 0 0

Now:

0 = background
1 = field instance 1
2 = field instance 2
3 = field instance 3

The values 1, 2 and 3 are not different land-cover classes. They are unique object identifiers.

This distinction is central to instance-segmentation training data.

B. What one prediction contains¶

A typical predicted instance contains several related outputs:

instance
├── class label
├── confidence score
├── bounding box
└── pixel-level mask

C. One class, many masks¶

The agricultural example illustrates an important point.

Suppose an image contains 35 fields.

You do not need:

35 semantic classes

You need:

1 semantic class: field
35 separate instances

This is why the practical training workflow later uses:

num_classes=2

for:

0 = background
1 = field

even though an image may contain many individual parcels.

Object identity comes from the masks, not from adding more semantic classes.

D. Why object identity matters¶

Once each object remains separate, you can perform object-level operations.

For example:

instance mask
     ↓
polygon
     ↓
one row in a GeoDataFrame
     ↓
area / perimeter / shape / attributes

This creates a familiar spatial data model:

The prediction has become a set of spatial features rather than only a raster class map.

E. Common instance errors¶

Instance segmentation introduces several error types beyond incorrect class labels.

F. Mask overlap¶

Intersection over Union (IoU) evaluates the geometric overlap between a predicted mask ($A$) and a reference mask ($B$):

For instance segmentation, the overlap is calculated using the mask pixels, rather than only the rectangular bounding boxes.

Higher mask IoU indicates stronger spatial agreement.

This becomes useful when calculating instance-level metrics such as Average Precision (AP).

4. Python reactivation¶

An instance-label raster loaded as a NumPy array behaves exactly like the class-label arrays from L07: numpy.unique(array) lists the distinct values present, only now those values represent individual object IDs rather than class indices. Subtracting one for the background value—len(numpy.unique(array)) - 1—is a quick way to count how many distinct objects a mask contains.

Suppose instance_mask is an array where zero is background and positive integers are individual object IDs:

import numpy as np

instance_mask = np.array(
    [
        [0, 0, 0, 0, 0],
        [0, 1, 1, 2, 0],
        [0, 1, 1, 2, 0],
        [0, 3, 3, 2, 0],
        [0, 0, 0, 0, 0],
    ]
)

np.unique(instance_mask)

You can filter for non-background IDs to get exact object numbers and identifiers:

instance_ids = np.unique(instance_mask)
instance_ids = instance_ids[instance_ids != 0]

print(f"Number of instances: {len(instance_ids)}")
print(f"IDs: {instance_ids}")

Or calculate the total count directly using the shortcut formula:

num_objects = len(np.unique(instance_mask)) - 1
print(f"Quick object count: {num_objects}")

While this is not how a neural network generates predictions, it demonstrates why an instance-labelled raster is useful: every object retains a distinct identity and can be selected independently.

5. Common pitfalls¶

• Assuming instance IDs are comparable across images. Field 3 in one prediction has no relationship to field 3 in a different image; IDs are only meaningful within a single prediction.

• Confusing the class-label and instance-label rasters. They answer different questions and are easy to mix up if you are not deliberate about which one you are looking at.

• Treating a low per-instance confidence score as a class-level problem. A low score on one field does not mean the model is generally uncertain about fields; check whether it is isolated to that specific object.

6. Mini task¶

You load an instance-label raster and find numpy.unique(array) returns [0, 1, 2, 3, 4, 5]. A colleague says “so the model found 6 fields.” Are they right? Explain.

7. Key takeaways¶

• Class labels answer “what class”; instance labels answer “which specific object,” using a distinct integer ID per object.

• geoai keeps class-label and instance-label rasters separate, matching the "class_label" and "instance" entries you will see in prediction output.

• Instance identifiers are only meaningful within a single prediction; they do not carry meaning across different images.

• Confidence scores in instance segmentation apply per object, the same principle as per-box confidence in detection.