Description

The Generate All Masks Route segments an image into every region the model can identify, and returns each region as its own binary mask.

Use it to build a full segmentation map of an image, then feed an individual mask into a mask-based route such as /erase or /gen_fill.

Output Characteristics

• Each mask is returned as a separate PNG at the same resolution as the input image, with the region set to 255 (white) and everything else to 0 (black).
• Masks are sorted by confidence, best first. id is the position in that order, starting at 1.
• area is the number of white pixels in the returned mask, measured at the input image's resolution.
• Masks may overlap, and one may contain another — a car and its rear window are returned as two separate masks. The same pixel can belong to several masks.
• Mask URLs are temporary and expire according to your organization's image retention policy. Download or copy any mask you intend to keep.

Example

One request returns every region the model finds, each as its own mask. The three below all came from the same call on the image shown.

<table> <tr> <th style="text-align: center;">Input Image</th> <th style="text-align: center;">Mask — road<br>_{area 7,704,780 · confidence 1.000}</th> <th style="text-align: center;">Mask — car<br>_{area 1,404,681 · confidence 0.999}</th> <th style="text-align: center;">Mask — person<br>_{area 358,414 · confidence 0.971}</th> </tr> <tr> <td align="center" style="vertical-align: middle;"> <img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene.jpg" width="200" style="border-radius: 8px;"> </td> <td align="center" style="vertical-align: middle;"> <img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene_mask_road.png" width="200" style="border-radius: 8px;"> </td> <td align="center" style="vertical-align: middle;"> <img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene_mask_car.png" width="200" style="border-radius: 8px;"> </td> <td align="center" style="vertical-align: middle;"> <img src="https://bria-datasets.s3.us-east-1.amazonaws.com/api_doc/all_masks/street_scene_mask_person.png" width="200" style="border-radius: 8px;"> </td> </tr> </table>

This request returned 65 masks. The labels above are ours, added for the example — the API returns no names for a mask, only id, area and confidence. Each pedestrian is a separate mask.

Choosing a mask

The model almost always returns one segment covering most or all of the image, and that segment is often ranked first by confidence. A featureless image returns exactly one such mask rather than an empty list.

A mask that covers the entire image cannot be used with /gen_fill, which requires a mask containing both black and white pixels and rejects an all-white one. Screening candidates by area avoids this.

Using a mask with /gen_fill and /erase

Neither /gen_fill nor /erase generates a mask for you — mask is a required parameter on both. A mask always comes from somewhere: a brush stroke drawn by your user, your own pipeline, or this route. Generate one here when you want the model to pick out the regions instead of asking a user to draw them.

/gen_fill also accepts a mask_type parameter, but it does not change how the mask is interpreted there; it is only meaningful for /erase. A mask from this route needs no particular value.

The mask you pass must have the same aspect ratio as the image. Masks from this route come back at the input image's resolution, so they already satisfy that when used with the image they were generated from.

Choosing between this route and the deprecated v1 route

New integrations should use this route. The older /v1/objects/mask_generator route returns a single ZIP archive of all masks plus a panoptic map, is deprecated, and orders its masks worst-first — the opposite of this route.

{
  "result": {
    "masks": [
      {
        "id": 1,
        "image_url": "https://temp.bria.ai/9c4d61bbc940/25476897e0c146f380a3fdbb944ab18e/a4f.png",
        "area": 120560,
        "confidence": 1
      }
    ]
  }
}