uiimage

Create image component

Syntax

im = uiimage

im = uiimage(parent)

im = uiimage(___,Name,Value)

Description

im = uiimage creates an image component in a new figure and returns the Image object. MATLAB^® calls the uifigure function to create the new figure. Use uiimage to display a picture, icon, or logo in your app.

im = uiimage(parent) creates an image component in the specified parent container. The parent can be a Figure object or one of its child containers.

im = uiimage(___,Name,Value) specifies Image properties using one or more Name,Value arguments. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

Display a Picture

Create an image component within a figure. The default image displays.

fig = uifigure;
im = uiimage(fig);

Now, add a picture to the image component.

im.ImageSource = "peppers.png";

Configure Image to Open Link When Clicked

Create an image and specify a URL that opens in a new browser tab when you click the image. Specify a tooltip that appears when you point to the image.

fig = uifigure;
im = uiimage(fig);
im.ImageSource = "ngc6543a.jpg";
im.URL = "https://www.mathworks.com/";
im.Tooltip = "Go to www.mathworks.com";

Before R2022b: Use the ImageClickedFcn property instead of the URL property and create a callback using a function handle.

im.ImageClickedFcn = @(src,event)web("https://www.mathworks.com/");

Display Animated GIF with Letterboxing

Create an image component that displays an animated GIF using the actual size of the image.

fig = uifigure;
im = uiimage(fig,"ImageSource","questions.gif");
im.ScaleMethod = "none";

Now, scale the image so that it fits within the default component area, preserving aspect ratio and without clipping. Then, apply a black background to create the appearance of letterboxing (black bars above and below the image).

im.ScaleMethod = "scaledown";
im.BackgroundColor = "black";

Describe Image Using Alt Text

Create an image component that displays a picture of a street. Provide a description of the image by specifying alt text (or alternative text) using the AltText property. Screen readers use this text to describe the image.

fig = uifigure;
im = uiimage(fig,ImageSource="street1.jpg", ...
    AltText="City street including cars, signs, and buildings");

Input Arguments

parent — Parent container

Figure object (default) | Tab object | Panel object | ButtonGroup object | GridLayout object

Parent container, specified as a Figure object or one of its child containers: Tab, Panel, ButtonGroup, or GridLayout. If you do not specify a parent container, MATLAB calls the uifigure function to create a new Figure object that serves as the parent container.

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: im = uiimage(ScaleMethod="none")

Note

The properties listed here are only a subset. For a complete list, see Image.

ImageSource — Image source or file

' ' (default) | file path | m-by-n-by-3 truecolor image array

Image source or file, specified as a file path or an m-by-n-by-3 truecolor image array. Supported image formats include JPEG, PNG, GIF, SVG, or m-by-n-by-3 truecolor image array.

For more information on truecolor image arrays, see Working with Image Types in MATLAB.

Example: im = uiimage(ImageSource="peppers.png");

Example: im.ImageSource = "C:\TEMP\ngc6543a.jpg";

ScaleMethod — Image scaling method

'fit' (default) | 'fill' | 'none' | 'scaledown' | 'scaleup' | 'stretch'

Image scaling method, specified as one of the values listed in the table. Use this name-value pair argument to specify how you want your image to render within the component area.

The table also demonstrates each scale method with an example image. In the rendered image examples, the BackgroundColor property of the image component has been set to 'magenta'. The scaling behavior of SVG image files may vary based on how the file is defined.

Value	Description	Example		Scales Up	Scales Down	Maintains Aspect Ratio	Clips Image
		Original Image	Rendered Image
'fit'	Scales in any direction to display the image within the component area, and maintains aspect ratio without clipping.			Yes	Yes	Yes	No
'fill'	Scales in any direction to fill the component area, maintaining aspect ratio and clipping if necessary.			Yes	Yes	Yes	Yes
'none'	Uses the actual size of the image and maintains aspect ratio. If the component area is smaller than the image, the image is clipped.			No	No	Yes	Yes
'scaledown'	Scales down and maintains aspect ratio without clipping. If the original image is larger than the component area, the image scales down and renders as if the ScaleMethod was set to 'fit'. If the original image is smaller than the component area, the image does not scale down and renders as if the ScaleMethod was set to 'none'.			No	Yes	Yes	No
'scaleup'	Scales up and maintains aspect ratio with clipping. If the original image is smaller than the component area, the image scales up and renders as if the ScaleMethod was set to 'fit'. If the original image is larger than the component area, the image does not scale up and renders as if the ScaleMethod was set to 'none'.			Yes	No	Yes	Yes
'stretch'	Scales in any direction to fill the component area, without maintaining the aspect ratio and without clipping.			Yes	Yes	No	No

URL — Image hyperlink URL

'' (default) | character vector | string scalar

Image hyperlink URL, specified as a character vector or string scalar. When a user clicks the image, the web address specified by the URL opens in a new browser tab. If the user is running the app in a browser using MATLAB Online™ or as a web app, the new tab opens in the current browser. Otherwise, the new tab opens in the default browser on the user's system.

ImageClickedFcn — Image clicked callback

' ' (default) | function handle | cell array | character vector

Image clicked callback, specified as one of these values:

• A function handle.

• A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

• A character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when the user clicks the image in the app. If you specify a link to open using the URL property, the callback executes after that link opens.

This callback function can access specific information about the user's interaction with the image. MATLAB passes this information in an ImageClickedData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.Source returns the Image object that the user is interacting with to trigger the callback. The ImageClickedData object is not available to callback functions specified as character vectors.

The following table lists the properties of the ImageClickedData object.

Property	Value
EventName	'ImageClicked'
Source	Component executing the callback

For more information about writing callbacks, see Callbacks in App Designer.

Position — Location and size of image component

[100 100 100 100] (default) | [left bottom width height]

Location and size of image component relative to the parent, specified as a four element vector of the form [left bottom width height]. This table describes each element in the vector.

Element	Description
left	Distance from the inner left edge of the parent container to the outer left edge of the image component
bottom	Distance from the inner bottom edge of the parent container to the outer bottom edge of the image component
width	Distance between the right and left outer edges of the image component
height	Distance between the top and bottom outer edges of the image component

The Position values are relative to the drawable area of the parent container. The drawable area is the area inside the borders of the container and does not include the area occupied by decorations such as a menu bar or title.

All measurements are in pixel units.

Tips

• For image analysis and processing, see graphics functions image and imshow. These functions provide additional options for displaying images, including control over image resolution and interpolation.

• If you need to update the contents of an image while the app is running, specify the ImageSource property as a truecolor image array instead of a file name. When you use an image array, the image display updates whenever the contents changes, even if the file name remains the same. For example, use this code to update an image in your app when the contents of the myimage.png file changes.

  imarray = imread("myimage.png");
  im.ImageSource = imarray;

Version History

Introduced in R2019a

R2023a: Specify image alt text

Specify the AltText property to provide a description of the image. Screen readers use this text to describe the image when an app user navigates through your app.

R2022b: Create an image hyperlink using the URL property

To open a web address when a user clicks an image in your app, specify the image URL property.