Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

caxis

Color axis scaling

Syntax

caxis([cmin cmax])
caxis auto
caxis manual
caxis(caxis)
v = caxis
caxis(target,...)

Description

caxis controls the mapping of data values to the colormap.

caxis([cmin cmax]) sets the color limits for the current axes or chart returned by the gca command. Data values less than cmin or greater than cmax map to cmin and cmax, respectively. Values between cmin and cmax linearly map to the current colormap.

caxis auto computes the color limits automatically using the minimum and maximum data values. This is the default behavior. Color values set to Inf map to the maximum color, and values set to -Inf map to the minimum color. Faces or edges with color values set to NaN are not drawn.

caxis manual and caxis(caxis) freeze the color axis scaling at the current limits. This enables subsequent plots to use the same limits when hold is on.

v = caxis returns a two-element row vector containing the [cmin cmax] currently in use.

caxis(target,...) uses the axes or chart specified by target instead of the current axes or chart.

Input Arguments

collapse all

Target, specified as an Axes object or a graphics object that has a ColorLimits property. For example, you can set or query the color limits for a HeatmapChart object.

If you do not specify the target, then the caxis function uses the graphics object returned by the gca command.

For Axes objects, caxis changes the CLim and CLimMode properties. It affects any surface, patch, or image with indexed CData and CDataMapping set to scaled. It does not affect surfaces, patches, or images with true color CData or with CDataMapping set to direct.

Examples

collapse all

Define X, Y, and Z as data for a sphere and view the data as a surface. Define the colors for the surface, C.

[X,Y,Z] = sphere;
C = Z;
surf(X,Y,Z,C)

Values of C are in the range [-1,1]. Values of C near -1 are assigned the lowest values in the colormap. Values of C near 1 are assigned the highest values in the colormap.

Map the top half of the surface to the highest value in the color table by setting the maximum color limit to 0.

caxis([-1,0])

Reset the axis scaling back to its default range.

caxis auto

Return the values of the current color limits.

v = caxis
v = 

    -1     1

Load the cape file which contains the image data, X, and the colormap, map, for Cape Cod, Massachusetts.

load cape

Display the image with CDataMapping set to scaled, and use the map colormap.

figure
image(X,'CDataMapping','scaled')
colormap(map)

The color limits span the range of the image data, which is 1 to 192. The blue color of the ocean is the first color in the colormap and is mapped to the lowest data value, 1. You can effectively move sea level by changing the lower color limit value using caxis.

Display the image data using four different color limit values.

load cape

figure
colormap(map)

subplot(2,2,1)
image(X,'CDataMapping','scaled')
title('caxis = [1 192]')

subplot(2,2,2)
image(X,'CDataMapping','scaled')
caxis([4,192]) % change caxis
title('caxis = [4 192]')

subplot(2,2,3)
image(X,'CDataMapping','scaled')
caxis([7,192]) % change caxis
title('caxis = [7 192]')

subplot(2,2,4)
image(X,'CDataMapping','scaled')
caxis([10,192]) % change caxis
title('caxis = [10 192]')

Tips

How Color Axis Scaling Works

Surface, patch, and image graphics objects having indexed CData and CDataMapping set to scaled map CData values to colors in the figure colormap each time they render. CData values equal to or less than cmin map to the first color value in the colormap, and CData values equal to or greater than cmax map to the last color value in the colormap. The following linear transformation is performed on the intermediate values (referred to as C below) to map them to an entry in the colormap (whose length is m, and whose row index is referred to as index below).

index = fix((C-cmin)/(cmax-cmin)*m)+1;
%Clamp values outside the range [1 m]
index(index<1) = 1;
index(index>m) = m; 

See Also

| | | | | | |

Introduced before R2006a

Was this topic helpful?