alpha

Add transparency to objects in axes

Syntax

alpha value

alpha alphadata

alpha facealpha

alpha alphadatamapping

alpha(obj,___)

alpha(ax,___)

Description

alpha value sets the face transparency for objects in the current axes that support transparency. Specify value as 'clear' or 'opaque', or as a number in the range [0, 1]. A value of 0 makes the objects transparent, and value of 1 makes the objects fully opaque.

alpha alphadata varies the transparency across all image, patch, surface, and scatter objects in the axes. This option sets the corresponding alpha data properties for the objects.

alpha facealpha controls the transparency of the faces for patch, surface, and scatter objects in the axes. This option sets the FaceAlpha on patch and surface objects. For scatter objects, it sets the MarkerFaceAlpha and MarkerEdgeAlpha properties.

alpha alphadatamapping controls the interpretation of the alpha data values for all image, patch, surface, and scatter objects in the axes. This option sets the AlphaDataMapping property on the objects.

alpha(obj,___) sets the transparency for the objects specified by obj. The option, obj, can precede any of the input arguments in the previous syntaxes. Use single quotes around input arguments that are character arrays, for example, alpha(obj,'opaque').

alpha(ax,___) sets the transparency for the objects in the axes specified by ax, instead of the current axes. Specify ax as the first input argument. You cannot specify both the ax and obj inputs.

Examples

Set Transparency for All Graphics Objects in Axes

Create a bar chart and a scatter chart. Set the face transparency for both the bar series and scatter series object to 0.5.

bar(1:10)
hold on
scatter(10*rand(10,1),10*rand(10,1),'filled','SizeData',200)
hold off
alpha(.5)

Set Transparency for Specific Graphics Object

Create a bar chart and a scatter chart. Set the transparency for the scatter series object to 0.5 without affecting the bar series object.

b = bar(1:10);
hold on
s = scatter(10*rand(10,1),10*rand(10,1),'filled','SizeData',200);
hold off
alpha(s,.5)

Set Surface Transparency Using z Values

Create a surface chart. Vary the transparency across the surface based on the z values.

s = surf(peaks);
alpha(s,'z')

Set Mapping of Alpha Data into Alphamap

Create an image. Vary the transparency across the image based on the color values. By default, the image clamps the transparency values between 0 and 1. Values less than 0 are completely transparency and values greater than 1 are completely opaque. Instead, transform the transparency values to span the alphamap using the alpha scaled command.

imagesc(peaks)
alpha color
alpha scaled

Input Arguments

value — Face transparency value

number in the range [0, 1] | 'clear' | 'opaque'

Face transparency value, specified as one of these values:

• Number in the range [0, 1] — Set the face transparency to the specified value. A value of 0 means transparent. A value of 1 means opaque. Values between 0 and 1 are partially transparent.

• 'clear' — Set the face transparency to 0 (transparent).

• 'opaque' — Set the face transparency to 1 (opaque).

If the object does not have a face or if the face has no color, then the alpha function does not have a visual effect on the object. For example, alpha does not have a visual effect on scatter objects that use unfilled markers or that use markers without a face ('*', '+', '.', and 'x').

This table lists the graphics objects that support transparency and the associated face transparency properties that updates to the value specified.

Graphics Object	Face Transparency Property
Area objects	FaceAlpha
Bar objects	FaceAlpha
Scatter objects	MarkerFaceAlpha, MarkerEdgeAlpha
Histogram and histogram2 objects	FaceAlpha
Image objects	AlphaData
Chart and primitive surface objects	FaceAlpha
Patch objects	FaceAlpha

alphadata — Option to vary transparency across object

'x' | 'y' | 'z' | 'color' | 'rand' | vector or matrix

Option to vary the transparency across the object, specified as one of the values in this table. The table columns indicate how each option affects the different types of objects, depending on what objects are contained in the axes.

Option	Surface Objects	Scatter Objects	Patch Objects	Image Objects
'x'	Sets the AlphaData property to be the same as the XData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData property to be the same as the XData property and sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'.	Sets the FaceVertexAlphaData property to be the same as the XData property and sets the FaceAlpha property to 'flat'.	No effect.
'y'	Sets the AlphaData property to be the same as the YData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData property to be the same as the YData property and sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'.	Sets the FaceVertexAlphaData property to be the same as the YData property and sets the FaceAlpha property to 'flat'.	No effect.
'z'	Sets the AlphaData property to be the same as the ZData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData property to be the same as the ZData property and sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'.	Sets the FaceVertexAlphaData property to be the same as the ZData property and sets the FaceAlpha property to 'flat'.	No effect.
'color'	Sets the AlphaData property to be the same as the CData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData property to be the same as the CData property and sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'.	Sets the FaceVertexAlphaData property to be the same as the FaceVertexCData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData data property to be the same as the CData property.
'rand'	Sets the AlphaData property to a matrix of random numbers the same size as the ZData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData property to a matrix of random numbers the same size as the XData property and sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'.	Sets the FaceVertexAlphaData property to a matrix of random numbers the same size as the ZData property and sets the FaceAlpha property to 'flat'.	Sets the AlphaData data property to a matrix of random numbers the same size as the CData property.
Create a vector or matrix A, and use the function form of the command. For example: A = [.1 .2; .3 .4] alpha(A)	Specify A as a matrix that is the same size as the CData property of the surface. The alpha function sets the AlphaData property to A and sets the FaceAlpha property to 'flat'.	Specify A as a vector that is the same size as the XData property of the scatter object. The alpha function sets the AlphaData property to A and sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'.	Specify A as a matrix that is the same size as the FaceVertexCData property of the patch. The alpha function sets the FaceVertexAlphaData property to A and sets the FaceAlpha property to 'flat'.	Specify A as a matrix that is the same size as the CData property of the image. The alpha function sets the AlphaData data property to A.

facealpha — Option for flat or interpolated face transparency

'flat' | 'interp' | 'texture'

Option for flat or interpolated face transparency, specified as one of the values in this table. The table columns indicate how each option affects the different types of objects, depending on what objects are contained in the axes.

Option	Surface Objects	Scatter Objects	Patch Objects
'flat'	Sets the FaceAlpha property to 'flat'. The AlphaData property must be an array the same size as the CData property. The FaceColor property must be set to 'flat'.	Sets the MarkerFaceAlpha and MarkerEdgeAlpha properties to 'flat'. The AlphaData property must be a vector the same size as the XData property. The MarkerFaceColor property must be set to 'flat'.	Sets the FaceAlpha property to 'flat'. The FaceVertexAlphaData property must be a column vector with length equal to the number of faces in the Faces property.
'interp'	Sets the FaceAlpha property to 'interp'. The AlphaData property must be an array the same size as the CData property. The FaceColor property must be set to 'interp'.	No effect.	Sets the FaceAlpha property to 'interp'. The FaceVertexAlphaData property must be a column vector with length equal to the number of vertices in the Vertices property.
'texture'	Sets the FaceAlpha property to 'texturemap'. The FaceColor property must be set to 'texturemap'.	No effect.	No effect.

alphadatamapping — Interpretation of alpha data values

'none' | 'direct' | 'scaled'

Interpretation of alpha data values, specified as 'none', 'direct', or 'scaled'. This option sets the AlphaDataMapping property for image, patch, surface, and scatter objects in the axes.

• 'none' — Interpret alpha data values as transparency values. A value of 0 or less is completely transparent. A value of 1 or greater is opaque. Values between 0 and 1 are semitransparent.

• 'direct' — Interpret the values as indices into the figure’s alphamap. Fix values with a decimal portion to the nearest lower integer. The Alphamap property of the figure contains the alphamap.

• 'scaled' — Transform the alpha data values to span the portion of the figure’s alphamap indicated by the ALim property of the axes. Linearly map the data values to alpha values.

obj — Graphics objects that support transparency

scalar | vector

Graphics objects that support transparency, specified as a scalar or vector. Use this option if you want to control which objects alpha affects. Otherwise, alpha affects all objects in the axes that support transparency.

Specify one or more of these types of objects:

• Area object

• Bar series object

• Scatter series object

• Histogram or histogram2 object

• Image object

• Patch object

• Chart or primitive surface object

Note

Not all objects support the alphadata, facealpha, and alphadatamapping input arguments. See the syntax descriptions for a list of objects that each option supports.

ax — Axes object

axes object

Axes object. If you do not specify the axes, then alpha sets the transparency for graphics objects in the current axes.

Compatibility Considerations

Scatter Objects Change When You Specify the alphadata, facealpha, or alphadatamapping arguments

Behavior changed in R2020b

Starting in R2020b, Scatter objects in the axes are affected when you call the alpha function with the alphadata, facealpha, or alphadatamapping arguments without specifying a particular object within the axes to modify.

In R2020a and earlier releases, the alphadata, facealpha, and alphadatamapping arguments have no effect on Scatter objects in the axes.

For example, this code creates a surface plot and a scatter plot, and then calls the alpha function to vary the transparency along the x-dimension. In R2020a, only the surface plot changes when you call the alpha function. In R2020b, both plots are affected.

[X,Y] = meshgrid(-10:10);
Z = ones(21,21) * -2;
surf(X,Y,Z)
hold on
scatter([-8 2 4 -5 5 3],[7 4 2 -1 -7 0],200,'filled')
alpha('x')

To prevent Scatter objects from changing, specify the object to modify as the first argument to the alpha function. For example, to update the preceding code, call the surf function with an output argument s. Then pass s to the alpha function to modify only the Surface object.

[X,Y] = meshgrid(-10:10);
Z = ones(21,21) * -2;
s = surf(X,Y,Z)
hold on
scatter([-8 2 4 -5 5 3],[7 4 2 -1 -7 0],200,'filled')
alpha(s,'x')