Cuboids

R2026b

Static 3-D cuboid annotation

Since R2026b

Description

A Cuboids object labels one or more static cuboids in a Viewer object. The properties of the object control the appearance and behavior of the static cuboid annotations.

Static ROIs provide high-performance annotations for images and volumes you display in a Viewer object using imageshow and volshow, respectively. Use static ROIs to draw large numbers of ROIs on a viewer. For best performance, specify all the static ROIs together in a single function call instead of creating multiple objects. Static ROIs are more efficient than customizable viewer-based ROIs because they support fewer properties for styling, labeling, and interactions. For a comparison of static viewer-based ROIs with other ROIs, see Choose Approach to Annotate ROIs in Images.

Creation

You can create a Cuboids object in these ways. For more information, see Create Static Viewer-Based ROIs.

Use the uiannotate function to create the ROI and display it in a specified viewer.
Use the images.ui.graphics.roi.static.Cuboids function described here. Display the ROI in a viewer by specifying the Parent property value as the target Viewer object during creation. Alternatively, display an ROI after you create it by adding the object to the Annotations property of a Viewer object.

Syntax

c = images.ui.graphics.roi.static.Cuboids

c = images.ui.graphics.roi.static.Cuboids(PropertyName=Value)

Description

c = images.ui.graphics.roi.static.Cuboids creates a Cuboids object with default property values. Use c to query and modify properties of the Cuboids object after you create it.

c = images.ui.graphics.roi.static.Cuboids(PropertyName=Value) sets one or more properties using name-value arguments.

Example: c = images.ui.graphics.roi.static.Cuboids(Position=[12 16 10 10 10 4; 30 30 10 10 10 4]) creates a Cuboids object consisting of two cuboid shapes.

example

Properties

expand all

Shape and Position

`Position` — Position of ROI
`[]` (default) | n-by-6 numeric matrix | n-by-9 numeric matrix

Position of the ROI, specified as an n-by-6 numeric matrix or an n-by-9 numeric matrix, where n is the number of static cuboids in the ROI. The Cuboids object stores the Position property as an n-by-9 numeric matrix.

The table describes the format of Position for axis-aligned cuboids and rotated cuboids.

Cuboid Orientation Format to Specify Position Property Format of Stored Position Property

Axis-aligned cuboids (omitting rotation angle)

Cuboid Orientation	Format to Specify Position Property	Format of Stored Position Property
Axis-aligned cuboids (omitting rotation angle)	Specify `Position` as an n-by-6 numeric matrix. Each row specifies an axis-aligned cuboid as a 6-element vector of the form `[xmin ymin zmin width height depth]`. `xmin`, `ymin`, and `zmin` specify the xyz-coordinates of the corner of the cuboid closest to the origin. `width`, `height`, and `depth` specify the extent of the cuboid in the x-, y-, and z- dimensions, respectively.	The `Cuboids` object stores the `Position` property as an n-by-9 numeric matrix. Each row represents an axis-aligned cuboid as a 9-element vector of the form `[xmin ymin zmin width height depth 0 0 0]`.
Rotated cuboids (with any rotation angle)	Specify `Position` as an n-by-9 numeric matrix. Each row specifies a rotated cuboid as a 9-element vector of the form `[xcen ycen zcen width height depth rotX rotY rotZ]`. `xcen`, `ycen`, and `zcen` specify the xyz-coordinates of the center of the cuboid. `width`, `height`, and `depth` specify the extent of the cuboid in the x-, y-, and z- dimensions, respectively. `rotX`, `rotY`, and `rotZ` specify the rotation angles in degrees about each axis. Each rotation is clockwise-positive with respect to the positive direction of the associated spatial axis. Rotation is applied assuming Euler angles in ZYX order.	The `Cuboids` object stores the `Position` property as an n-by-9 numeric matrix. Each row represents a rotated cuboid as a 9-element vector of the form `[xcen ycen zcen width height depth rotX rotY rotZ]`.

Specify Position as an n-by-6 numeric matrix. Each row specifies an axis-aligned cuboid as a 6-element vector of the form [xmin ymin zmin width height depth].

xmin, ymin, and zmin specify the xyz-coordinates of the corner of the cuboid closest to the origin.
width, height, and depth specify the extent of the cuboid in the x-, y-, and z- dimensions, respectively.

The Cuboids object stores the Position property as an n-by-9 numeric matrix. Each row represents an axis-aligned cuboid as a 9-element vector of the form

[xmin ymin zmin width height depth 0 0
                                 0]

Rotated cuboids (with any rotation angle)

Specify Position as an n-by-9 numeric matrix. Each row specifies a rotated cuboid as a 9-element vector of the form [xcen ycen zcen width height depth rotX rotY rotZ].

xcen, ycen, and zcen specify the xyz-coordinates of the center of the cuboid.
width, height, and depth specify the extent of the cuboid in the x-, y-, and z- dimensions, respectively.
rotX, rotY, and rotZ specify the rotation angles in degrees about each axis. Each rotation is clockwise-positive with respect to the positive direction of the associated spatial axis. Rotation is applied assuming Euler angles in ZYX order.

The Cuboids object stores the Position property as an n-by-9 numeric matrix. Each row represents a rotated cuboid as a 9-element vector of the form

[xcen
                                    ycen zcen width height depth rotX rotY rotZ]

Note

If you specify the position of a cuboid as a 9-element vector, then the Cuboids object interprets the cuboid as a rotated cuboid, regardless of the value of the rotation angles. As a result, if you specify all rotation angles as 0, the position vector has the form [xcen ycen zcen width height depth 0 0 0], not [xmin ymin zmin width height depth 0 0 0].

`Transformation` — Geometric transformation
`affinetform2d` object | `affinetform3d` object | `imref2d` object | `imref3d` object | 4-by-4 numeric matrix | ...

Geometric transformation that maps the intrinsic coordinate system to a world or map coordinate system, specified as one of the following.

2-D geometric transformation object: affinetform2d, rigidtform2d, simtform2d, or transltform2d
3-D geometric transformation object: affinetform3d, rigidtform3d, simtform3d, transltform3d
Spatial referencing object: imref2d or imref3d object.
Mapping reference object: MapCellsReference (Mapping Toolbox) or MapPostingsReference (Mapping Toolbox) (requires Mapping Toolbox™).
Matrix of data type double representing a 3-D affine geometric transformation. A valid 3-D affine transformation A has the form:

$Α = [\begin{matrix} a & b & c & d \\ e & f & g & h \\ i & j & k & l \\ 0 & 0 & 0 & 1 \end{matrix}]$

By default, Transformation is a 4-by-4 identity matrix.

Color and Styling

`Color` — ROI color
RGB triplet | hexadecimal color code | color name | short color name | n-by-3 numeric matrix

ROI color, specified as an RGB triplet, a hexadecimal color code, a color name, or a short color name. You can also specify multiple colors as an n-by-3 numeric matrix where each row is an RGB triplet. If you specify a single color, then all shapes in the ROI display with the same color. If you specify multiple colors, then n must be equal to the number of shapes in the ROI.

This table shows the default colors for static ROIs.

RGB Triplet	Appearance	Default Use
`[0 0.5610 1]`		This is the default color when creating a static ROI in dark mode.
`[0.8660 0.3290 0]`		This is the default color when creating a static ROI in light mode.

For a custom color, specify an RGB triplet or a hexadecimal color code.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1], for example, [0.4 0.6 0.7].
A hexadecimal color code is a string scalar or character vector that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Therefore, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and the hexadecimal color codes.

Color Name	Short Name	RGB Triplet	Hexadecimal Color Code
`"red"`	`"r"`	`[1 0 0]`	`"#FF0000"`
`"green"`	`"g"`	`[0 1 0]`	`"#00FF00"`
`"blue"`	`"b"`	`[0 0 1]`	`"#0000FF"`
`"cyan"`	`"c"`	`[0 1 1]`	`"#00FFFF"`
`"magenta"`	`"m"`	`[1 0 1]`	`"#FF00FF"`
`"yellow"`	`"y"`	`[1 1 0]`	`"#FFFF00"`
`"black"`	`"k"`	`[0 0 0]`	`"#000000"`
`"white"`	`"w"`	`[1 1 1]`	`"#FFFFFF"`

This table lists the default color palettes for plots in the light and dark themes.

Palette Palette Colors

Palette	Palette Colors
`"gem"` — Light theme default Before R2025a: Most plots use these colors by default.
`"glow"` — Dark theme default

"gem" — Light theme default

Before R2025a: Most plots use these colors by default.

"glow" — Dark theme default

You can get the RGB triplets and hexadecimal color codes for these palettes using the orderedcolors and rgb2hex functions. For example, get the RGB triplets for the "gem" palette and convert them to hexadecimal color codes.

RGB = orderedcolors("gem");
H = rgb2hex(RGB);

Example: Color="r" specifies that all shapes of the ROI are colored red.

Example: Color=[0 0.447 0.741] specifies that all shapes of the ROI have a custom color define by the RGB triplet [0 0.447 0.741].

Example: Color=parula(5) specifies that each of five shapes within an ROI have a different color from the parula colormap.

`Alpha` — Opacity of ROI
`1` (default) | number in range [0, 1]

Opacity of the ROI, specified as a number in the range [0, 1]. When the value is 1, the ROI is completely opaque. When the value is 0, the ROI is completely transparent.

`FaceAlpha` — Opacity of ROI face
`0.2` (default) | scalar in range [0, 1]

Opacity of the ROI face, specified as a scalar in the range [0, 1]. When the value is 1, the ROI face is completely opaque. When the value is 0, the ROI face is completely transparent.

`OrientationStem` — Display orientation stems
`"off"` (default) | `"on"` | on/off logical value

Display orientation stems, specified as "on" or "off", or as a numeric or logical 0 (false) or 1 (true). A value of "on" is equivalent to true, and "off" is equivalent to false. The object stores the value as an on/off logical value of type OnOffSwitchState.

Value	Description
`"on"`	Display orientation stems.
`"off"`	Hide orientation stems.

`Visible` — ROI visibility
`"on"` (default) | `"off"` | on/off logical value

ROI visibility, specified as "on" or "off", or as a numeric or logical 0 (false) or 1 (true). A value of "on" is equivalent to true, and "off" is equivalent to false. The value is stored as an on/off logical value of type OnOffSwitchState.

Value	Description
`"on"`	Display the ROI.
`"off"`	Hide the ROI without deleting it. You can still access the properties of an invisible ROI.

Identifiers

`Parent` — ROI parent
`Viewer` object

ROI parent, specified as a Viewer object. You can create a Viewer object for a 2-D image display or 3-D volume display by using the viewer2d or viewer3d function, respectively.

`Tag` — Tag to associate with ROI
`''` (default) | character vector | string scalar

Tag to associate with the ROI, specified as a character vector or string scalar. This property has no effect on the display, and the viewer does not use this property. You can use this property to track annotations for app building.

`UserData` — Data to associate with ROI
any MATLAB^® data

Data to associate with the ROI, specified as any MATLAB data. For example, you can specify a scalar, vector, matrix, cell array, string, character array, table, or structure. This property has no effect on the display, and the viewer does not use this property. You can use this property to append metadata to the ROI for app building.

Examples

collapse all

Create Static Cuboids Annotation Object

Open Live Script

Load an image volume containing spheres and display it. The viewer is the parent of the object returned by volshow.

load("spheresVol.mat")
obj = volshow(V);

viewer = obj.Parent;

Create a Cuboids object and display it in the viewer, using the Position property to specify the position of two cuboids in the form [xmin ymin zmin width height depth]. A single object that contains all the annotations renders more efficiently than separate objects.

pos = [47 10 58 25 25 25;
    32 62 55 25 25 25];
c = images.ui.graphics.roi.static.Cuboids(Position=pos,Parent=viewer);

Version History

Introduced in R2026b

Cuboids

Description

Creation

Syntax

Description

Properties

Shape and Position

`Position` — Position of ROI
`[]` (default) | n-by-6 numeric matrix | n-by-9 numeric matrix

`Transformation` — Geometric transformation
`affinetform2d` object | `affinetform3d` object | `imref2d` object | `imref3d` object | 4-by-4 numeric matrix | ...

Color and Styling

`Color` — ROI color
RGB triplet | hexadecimal color code | color name | short color name | n-by-3 numeric matrix

`Alpha` — Opacity of ROI
`1` (default) | number in range [0, 1]

`FaceAlpha` — Opacity of ROI face
`0.2` (default) | scalar in range [0, 1]

`OrientationStem` — Display orientation stems
`"off"` (default) | `"on"` | on/off logical value

`Visible` — ROI visibility
`"on"` (default) | `"off"` | on/off logical value

Identifiers

`Parent` — ROI parent
`Viewer` object

`Tag` — Tag to associate with ROI
`''` (default) | character vector | string scalar

`UserData` — Data to associate with ROI
any MATLAB^® data

Examples

Create Static Cuboids Annotation Object

Version History

See Also

Topics

Cuboids

Description

Creation

Syntax

Description

Properties

Shape and Position

Position — Position of ROI [] (default) | n-by-6 numeric matrix | n-by-9 numeric matrix

Transformation — Geometric transformation affinetform2d object | affinetform3d object | imref2d object | imref3d object | 4-by-4 numeric matrix | ...

Color and Styling

Color — ROI color RGB triplet | hexadecimal color code | color name | short color name | n-by-3 numeric matrix

Alpha — Opacity of ROI 1 (default) | number in range [0, 1]

FaceAlpha — Opacity of ROI face 0.2 (default) | scalar in range [0, 1]

OrientationStem — Display orientation stems "off" (default) | "on" | on/off logical value

Visible — ROI visibility "on" (default) | "off" | on/off logical value

Identifiers

Parent — ROI parent Viewer object

Tag — Tag to associate with ROI '' (default) | character vector | string scalar

UserData — Data to associate with ROI any MATLAB® data

Examples

Create Static Cuboids Annotation Object

Version History

See Also

Topics

`Position` — Position of ROI
`[]` (default) | n-by-6 numeric matrix | n-by-9 numeric matrix

`Transformation` — Geometric transformation
`affinetform2d` object | `affinetform3d` object | `imref2d` object | `imref3d` object | 4-by-4 numeric matrix | ...

`Color` — ROI color
RGB triplet | hexadecimal color code | color name | short color name | n-by-3 numeric matrix

`Alpha` — Opacity of ROI
`1` (default) | number in range [0, 1]

`FaceAlpha` — Opacity of ROI face
`0.2` (default) | scalar in range [0, 1]

`OrientationStem` — Display orientation stems
`"off"` (default) | `"on"` | on/off logical value

`Visible` — ROI visibility
`"on"` (default) | `"off"` | on/off logical value

`Parent` — ROI parent
`Viewer` object

`Tag` — Tag to associate with ROI
`''` (default) | character vector | string scalar

`UserData` — Data to associate with ROI
any MATLAB^® data