Mask Labeling¶

The Mask Labeling panel is an interactive tool for painting pixel-accurate segmentation masks on your MCAM images. It is used to create the labelled training data that segmentation models learn from, and to hand-correct masks that a model has already produced.

Open the MCAM viewer software, drag your dataset into the window so it loads in the viewer, then go to Tools > Mask Labeling. The panel opens on the right hand side.

This guide is split into three parts:

Part 1 — Manual tools — the painting and clean-up tools that work entirely by hand.
Part 2 — AI-assisted tools — the AI-assisted tools that propose masks for you.
Part 3 — Best practices — how to label effectively so the AI helps rather than hinders.

Objects and classes¶

Every pixel you paint is assigned to an object, identified by an integer object ID. Object IDs start at 1; the value 0 is reserved for unlabeled content. The Classes panel groups objects under names and colours, and the View toggle switches the display between Objects (each object drawn separately) and Classes (objects sharing a class drawn together). Use + Add Class to create a new class, and edit its name inline.

Throughout this guide the running example follows a real labelling session on brightfield adherent neurons, where three object IDs were used. The adherent neurons here are a stand-in for any adherent cell line — the same approach applies whatever cell type you are labelling.

Object ID	What it labels
`1`	Adherent neurons — the objects of interest.
`2`	Background — everything that is not an adherent neuron.
`3`	Contamination — debris, scratches, and hair on the plate.

Labelling the background and contamination explicitly (rather than just leaving them unlabelled) is not busywork: the assisted tools learn what each object is by contrasting it against the other objects, so a well-labelled background makes the adherent-neuron proposals far more reliable. This is covered in Part 3 — Best practices.

Part 1 — Manual tools¶

These are the tools in the Mask Tools section that operate purely on what you paint. None of them call the AI model.

Painting tools¶

Tool	Hotkey	What it does
Draw	`D`	Paint the current object ID under the cursor. The stroke width is set by Size.
Fill	`F`	Flood-fill a contiguous region with the current object ID.
Erase	`E`	Erase the mask under the cursor, returning those pixels to unlabeled content.
Select	—	Click an image tile to make it the active tile without painting. Many tools (Dilate, Erode, Clear, the assisted tools) act on the selected tile.
Next ID	`X`	Jump to the highest unused object ID for this image — i.e. start a fresh object.

The Size spin box sets the brush/line width in pixels for Draw and Erase. You can also adjust it on the fly with Ctrl + Scroll wheel. The colour swatch next to it shows the colour currently painted for the active object ID.

The ID spin box holds the object ID that Draw and Fill paint with. Two shortcuts make switching objects quick:

Shift + Scroll wheel — cycle the object ID.
Shift + Click — pick the object ID of whatever you click on.

History and clearing¶

Tool	Hotkey	What it does
Undo	`Ctrl+Z`	Undo the last action.
Redo	`Ctrl+Y`	Redo the last undone action.
Clear	`C`	Clear the entire mask for the image you click on.

Morphology (clean-up) tools¶

These reshape the mask of the current object on the selected tile. They are sized by the brush radius, so the Size value controls how aggressive they are.

Tool	What it does
Dilate	Grow the current object outward by the brush radius.
Erode	Shrink the current object inward by the brush radius.
Open	Remove small specks (an erode followed by a dilate). Use this to delete stray pixels smaller than your brush — for example a few isolated pixels left behind after a proposal.
Close	Fill small holes (a dilate followed by an erode). Use this to close the little gaps that appear inside an otherwise solid object.
Expand	Grow every object on the selected tile outward into the unlabeled content by the brush radius, splitting any overlaps by nearest object. Existing labels are never overwritten. This is how you push a set of objects out to fill the remaining gaps and reach full coverage — see Part 3 — Best practices.

Drawing overlapping masks¶

Each pixel is only ever associated with a single class — masks do not stack, so a pixel belongs to exactly one object (and therefore one class) at a time. Because of that, when a stroke (or an assisted proposal) lands on pixels that already belong to a different object, the On overlap radio buttons decide which one gives way:

Preserve (default) — pixels already labelled as another object are left untouched. Use this when you want to add labels without disturbing what you have already carefully drawn.
Replace — new paint or the proposal overwrites the existing label. Use this when you deliberately want to re-assign pixels from one object to another.

Loading existing masks¶

The Load Existing Masks section lets you continue from masks you (or a model) saved earlier: pick a mask set from the Masks drop-down and click Load Selected Masks. You can then correct them with any of the tools above. Editing an existing mask is usually far quicker than labelling from scratch.

Display options¶

The Display options section controls what is drawn on top of the image; none of it changes the labels themselves.

Option	What it does
Show Masks	Toggle the coloured mask overlay on and off. Turning it off reveals the raw image underneath, which is the fastest way to check whether a proposal is really covering the right pixels. The opacity slider next to it fades the overlay without hiding it completely.
Show Bounding Boxes	Draw a bounding box around each object.
Show IDs	Draw each object’s ID number on the image.

Saving¶

Click Save Mask Labels to write the masks (and their class names) back to the dataset.

Part 2 — AI-assisted tools¶

The Assisted Labelling (beta) section proposes masks for you. Under the hood it builds a nearest-neighbour model of what each object ID looks like from the pixels you have already painted, then finds every other pixel that resembles the object you are working on — while pushing away from the pixels you labelled as other objects. A proposal is shown as a translucent preview; you then decide how much of it to keep.

The typical rhythm is: Extend to get a first proposal, tune the Similarity threshold, optionally Grow to reach further, then commit with Union. Switch the object ID and repeat.

Generating a proposal¶

Button	What it does
Extend Selected Object	Extend the object currently in the ID box to every similar pixel on the selected tile. Work one object at a time; change the object ID to extend a different object.
Grow	Re-propose using the current proposal as the new seed, so the object’s appearance is re-estimated from the accepted pixels and the region expands further. Pressing Grow repeatedly keeps reaching outward, but it is a greedy step — it is not always the direction you want, so check each result.
Live	A toggle. While on, the selected object is re-proposed from the cached image features after every stroke, so you see the proposal update as you paint. Prime a tile with Extend first so the features are cached.

The Similarity threshold slider (default 0.95) is the main knob. A high threshold accepts only pixels that are very similar to what you painted (few proposals, but confident ones); lowering it accepts more (more coverage, but more risk of false positives). The useful range is usually 0.8–0.95, but once you have a lot of background labelled you can often drop it well below 0.5 safely, because the model then knows what not to accept.

Committing a proposal¶

A proposal does nothing to your labels until you commit it with one of these. Most of the time you will want Union, which simply adds the proposal to the selected object:

Button	What it does
Union	Add the proposal to the selected object (grow it). This is the one you will use most.
Intersect	Keep only the pixels the object and the proposal have in common.
Replace	Make the object exactly the proposal.
Discard	Throw the proposal away without changing anything.

Seeding from neighbours¶

Seed Labels from Neighbor → Current Object labels the active image using the labels already painted on its five nearest labelled neighbours: it learns the selected object’s appearance (and the background) from their masks and applies it here. The active image’s own pixels are never used, so this is a way to propagate a labelling style across a well plate. Picking a different object ID learns a different object.

Model and matching options¶

These shape how similarity is computed. The defaults are sensible for most work; reach for them when proposals are not landing where you expect.

Model — the feature backbone, colour handling, and precision used to describe the image. (mono) variants collapse the input to a single channel.
Object Similarity
- Normalize tile drift (on by default) — evens out brightness differences between tiles so an object seeded in one corner is still matched in a far corner of the same image.
- Global tile positions (on by default) — each tile remembers where it really sat in the whole image, which prevents a repeating grid of false positives.
- Position-free — ignore where things are and match purely on appearance, so look-alikes anywhere in the image are found. Overrides Global tile positions.
- Position-robust — find matches all over the image rather than only near the seed, while keeping the image features intact so the matches stay good.
Object size presets pick the analysis resolution and tiling behind the scenes:
- Small — native resolution, tiled — the finest detail, best for small or dense objects (like individual adherent neurons).
- Medium — larger tiles downsampled before encoding.
- Large — the whole tile downsampled, no tiling — fastest, best for big objects.
- Custom — expose the raw resolution / tile size / overlap fields.
Larger models and larger tiles are slower and can be too specific; if a proposal is not generalising, try a smaller preset.

Part 3 — Best practices¶

The following practices come from labelling sessions on difficult, partly out-of-focus brightfield samples. They are the difference between the AI saving you time and the AI making more work.

Only accept true positives¶

Raise the similarity threshold until there are no mistakes in the proposal, even if that means the proposal is sparse. If you are not sure a pixel belongs, leave it out. A false positive does not just add one wrong pixel — it corrupts the model’s idea of the object and makes every later proposal worse. False positives are trivially easy to generate, so there is never a reason to include a doubtful one; just do not paint over that region at all.

Label the background — and let the classes push off each other¶

The single biggest lever is labelling the background as its own object, not just the thing you care about. The assisted model learns each object by contrast, so background labels act as the opposite class that your object can push away from. In practice:

Label a few strong true positives for your object of interest (ID 1).
Switch to ID 2 and label background the same way.
Bounce back and forth — extend the object, extend the background, and each pass sharpens the other.
When a distinct third thing appears (here, contamination), give it its own ID (ID 3). Now the model separates adherent neurons from background and from debris.

Once a lot of background is labelled, the model becomes strikingly robust and you can drop the similarity threshold far lower than you could at the start.

Label fast, and prefer high-quality labels¶

Zoom in and quickly paint the true positives you are sure about; do not agonise over the initial mask. Label as much as you confidently can before you slow down. Clean, confident labels are always worth more than a larger, noisier set.

Affirm, don’t erase¶

When a proposal puts a label where it does not belong, it is almost always better to label that region as the class it really is (e.g. mark it as background with Replace) than to erase it. An affirmative label teaches the model something; erasing just removes information. Reserve erasing for sweeping away a large swath you never intend to keep.

Use the raw image and the clean-up tools¶

Toggle Show Masks off and on constantly to check a proposal against the underlying image — many pixels are genuine judgement calls (a slightly darker circle that might be a cell or might be debris) and you can only decide by looking. Use Open to sweep away specks smaller than your brush, and Close to fill the little gaps that riddle out-of-focus regions.

Aim for full coverage, then Expand¶

A good end state is one where every pixel carries one of your classes. Work the gaps down with the assisted tools, and when only thin seams remain, press Expand to grow all objects into the leftover unlabeled content (splitting overlaps by nearest object, never overwriting existing labels). This snaps the image to full coverage in one step. You can always Undo it.

Correcting an existing mask¶

Editing is much easier than labelling from nothing. If you start from a model’s output (for example a confluence mask), the most effective first move is to label the background, Expand it, and then work off that — the assisted tools are at their best when there is a solid background to push against. From there, toggle the overlay and make corrections rather than redrawing.