Documentation Center

  • Trial Software
  • Product Updates

Mapping Data to Transparency — Alpha Data

What Is Alpha Data?

Alpha data is analogous to color data (e.g., the CData property of surfaces). When you create a surface, MATLAB® rendering software maps each element in the color data array to a color in the colormap. Similarly, each element in the alpha data maps to a transparency value in the alphamap.

Specify surface and image alpha data with the AlphaData property. For patch objects, use the FaceVertexAlphaData property.

You can control how MATLAB interprets alpha data with the following properties:

  • FaceAlpha and EdgeAlpha — Enable you to select flat or interpolated transparency rendering. If set to a single transparency value, MATLAB applies this value to all faces or edges and does not use the alpha data.

  • AlphaDataMapping and ALim — Determine how MATLAB maps the alpha data to the alphamap. By default, MATLAB scales the alpha data to be within the range [0 1].

  • Alphamap — Contains the actual transparency values to which the data is to be mapped.

There are differences between the default values of equivalent color and alpha properties because, in contrast to color, transparency is not displayed by default. The following table highlights these differences.

Color Property

Default

Alpha Property

Default

FaceColor

Flat

FaceAlpha

1 (opaque)

CData

Equal to ZData

AlphaData and FaceVertexAlphaData

1 (scalar)

By default, objects have single-valued alpha data. Therefore you cannot specify flat or interp FaceAlpha or EdgeAlpha without first setting AlphaData to an array of the appropriate size.

The sections that follow illustrate how to use these properties to display object data as degrees of transparency.

Size of the Alpha Data Array

In order to use nonscalar alpha data, you need to specify the alpha data as an array equal in size to

  • CData of images and surfaces

  • The number of faces (flat) or the number of vertices (interpolated) defined in the FaceVertexAlphaData property of patches

Once you have specified an alpha data array of the proper size, you can select the face and edge rendering you want to use. Flat uses one transparency value per face, while interpolated performs bilinear interpolation of the values at each vertex.

Mapping Alpha Data to the Alphamap

You can control how MATLAB maps the alpha data to the alphamap using the AlphaDataMapping property. There are three possible mappings:

  • none — Interpret the values in alpha data as transparency values (data values must be between 0 and 1, or will be clamped to 0 or 1).

  • scaled — Transform the alpha data to span the portion of the alphamap indicated by the axes ALim property, linearly mapping data values to alpha values. This is the same way color data is mapped to the colormap.

  • direct — Use the alpha data directly as indices into the figure alphamap.

By default, objects have scalar alpha data (AlphaData and FaceVertexAlphaData) set to the value 1.

Example — Mapping Data to Color or Transparency

This example displays a surface plot of a function of two variables. The color is mapped to the gradient of the z data.

[x,y] = meshgrid([-2:.2:2]);
z = x.*exp(-x.^2-y.^2);
surf(x,y,z,gradient(z)); axis tight

You can map transparency to the gradient of z in a similar way.

surf(x,y,z,'FaceAlpha','flat',...
   'AlphaDataMapping','scaled',...
   'AlphaData',gradient(z),...
   'FaceColor','blue');
axis tight

Was this topic helpful?