uipaint

Draw using paintbrush in viewer window

Since R2026a

Syntax

BW = uipaint(Im)

BW = uipaint(Im,Name=Value)

Description

BW = uipaint(Im) enables an interactive paintbrush tool within the specified image viewer, where Im is an Image object returned by the imageshow function. The image viewer enters an interactive painting mode, in which you can draw and erase overlay pixels and accept the updated overlay. The function returns the pixels you draw as a binary mask and updates the OverlayData property of Im.

BW = uipaint(Im,Name=Value) specifies additional options using one or more name-value arguments. For example, OverlayValue=3 sets the OverlayData property value of the pixels you draw to 3.

Examples

Draw Image Overlay Using Paintbrush

Display an image in a viewer window by using the imageshow function. Specify the output argument to create a handle to the Image object.

Im = imageshow("peppers.png");

Enable the paintbrush mode by using the uipaint function. Optionally, to return the pixels you draw as a binary mask, specify the output argument bw.

bw = uipaint(Im);

In the viewer window, the toolbar and pointer change to paintbrush mode. To draw the label overlay, click the image and drag. While painting, you can use the Paint dropdown in the toolbar to switch between painting and erasing. Alternatively, you can hold Ctrl to use the eraser tool. To draw with finer detail, zoom in on the image using the mouse wheel.

The viewer blocks the MATLAB® command line while in paint mode. To finish drawing and deactivate the paint brush tool, click the Accept icon in the viewer toolbar or press Enter.

Display the binary output mask. The mask matches the pixels you draw during the paintbrush interaction.

imageshow(bw)

Draw Multiple Image Labels Using Paintbrush

Display an image using imageshow, specifying an output argument to create a handle to the Image object.

Im = imageshow("coins.png");

Draw a mask that contains all the nickels in the image using the default overlay value of 1. To finish drawing, press Enter or click the Accept icon to create the mask.

nickels = uipaint(Im);

Draw a mask that contains the dimes in the image. To display the dimes label using a different color, specify the OverlayValue name-value argument as 2. Alternatively, if you do not need the imageshow overlay colors to be different, each use of uipaint generates a separate binary mask, even if you do not specify OverlayValue.

dimes = uipaint(Im,OverlayValue=2);

This screenshot shows the display after interactively labeling nickels and dimes.

Display the binary masks of the nickels and dimes.

imageshow(nickels)

imageshow(dimes)

You can use the binary masks for image analysis and processing. In this case, count the number of dimes. Alternatively, you can calculate the total area occupied by nickels versus dimes using bwarea, or sharpen the regions within the nickel masks using roifilt2.

cc = bwconncomp(dimes);
numDimes = cc.NumObjects

numDimes = 
4

Draw Categorical Labels Using Paintbrush

Use the paintbrush to draw labels within a categorical label image.

Load buildingPixelLabeled, which includes an image (img) and the corresponding categorical labeled version of the image (label), into the workspace.

load buildingPixelLabeled
whos

  Name         Size                Bytes  Class          Attributes

  img        480x640x3            921600  uint8                    
  label      480x640              307698  categorical              

List the categories in the label image.

categories(label)

ans = 4×1 cell
    {'sky'     }
    {'grass'   }
    {'building'}
    {'sidewalk'}

Display the image by using imageshow, specifying the label image as an overlay.

Im = imageshow(img,OverlayData=label);

Use the paint brush to refine the labels at the edge of the sidewalk. Use the OverlayValue name-value argument to draw using the sidewalk category label.

mask = uipaint(Im,OverlayValue="sidewalk");

This screenshot shows the image after using the paintbrush.

Note that the output mask contains only the pixels you draw using the paintbrush. To save the complete updated label image, extract it from the OverlayData property of the image display object.

newLabel = Im.OverlayData;

Input Arguments

Im — Image to paint on

Image object

Image to paint on, specified as an Image object returned by the imageshow function.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: uipaint(Im,OverlayValue=3) sets the OverlayData property value of the pixels you draw to 3.

BrushSize — Paintbrush radius

25 (default) | positive integer

Paintbrush radius, in screen pixels, specified as a positive integer. Because the brush size corresponds to screen pixels and not image data pixels, the portion of the image the paintbrush covers depends on the zoom level. Zoom in to refine a small region of the overlay mask, and zoom out to paint a large region without needing to change the brush size.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

BrushAlpha — Paintbrush transparency

numeric scalar

Paintbrush transparency, specified as a numeric scalar in the range [0, 1]. By default, the brush transparency matches the transparency of the overlay specified by OverlayValue.

This value controls the transparency of the brush while drawing, and does not control the final overlay transparency. To control the transparency of the overlay, specify the OverlayAlpha property of Im.

Example: BrushAlpha=0.25

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

OverlayValue — Image overlay value

1 (default) | numeric scalar | string scalar

Image overlay value for the paintbrush, specified as a numeric scalar or string scalar. If the OverlayData of Im contains numeric values, specify the overlay value as a numeric scalar. If the OverlayData of Im is a categorical image, specify the overlay value as a nonnegative integer that maps to a category or as a string scalar that matches a category name. The overlay value determines these paintbrush behaviors.

• The value assigned in the OverlayData property of Im for each pixel you draw with the paintbrush.

• The color in the OverlayColormap property of Im the paintbrush matches while drawing.

Example: OverlayValue=3

Example: OverlayValue="grass"

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | string

Output Arguments

BW — Binary mask image

logical array

Binary mask image, returned as a logical array.

Data Types: logical

Tips

• The MATLAB^® command line is blocked while the paintbrush tool is enabled. To turn off the paintbrush, accept the updated overlay in the viewer toolbar.

• A pixel is true in the output mask if the paintbrush tool paints the center of the pixel.

• In addition to specifying the BrushSize name-value argument, you can change the brush size while painting by clicking inside the viewer and holding Shift while scrolling the mouse wheel.

• Depending on your use case, you can get the labels you paint using the uipaint function in these ways.

  • Screenshot — To capture and view the image overlay outside MATLAB, right-click the image and select Copy screenshot to clipboard or Save screenshot to file.

  • Binary mask — To access the pixels drawn during only one paintbrush interaction, get the corresponding output mask BW.

  • Label image — To access the complete overlay image for an Image object, access the OverlayData property of that object using dot notation. Each overlay color represents a different OverlayData value.

Version History

Introduced in R2026a