Main Content

alpha

Add transparency to objects in axes

Description

example

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.

example

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.

example

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.

example

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

collapse all

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)

Figure contains an axes object. The axes object contains 2 objects of type bar, scatter.

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)

Figure contains an axes object. The axes object contains 2 objects of type bar, scatter.

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

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

Figure contains an axes object. The axes object contains an object of type surface.

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

Figure contains an axes object. The axes object contains an object of type image.

Input Arguments

collapse all

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 objectsFaceAlpha
Bar objectsFaceAlpha
Scatter objectsMarkerFaceAlpha, MarkerEdgeAlpha
Histogram and histogram2 objectsFaceAlpha
Image objectsAlphaData
Chart and primitive surface objectsFaceAlpha
Patch objectsFaceAlpha

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.

OptionSurface ObjectsScatter ObjectsPatch ObjectsImage 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.

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.

OptionSurface ObjectsScatter ObjectsPatch 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.

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.

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.

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

Compatibility Considerations

expand all

Behavior changed in R2020b

Introduced before R2006a