Documentation Center

  • Trials
  • Product Updates

Axes Color Limits — the CLim Property

Introduction

Many 3-D plotting functions produce graphs that use color as another data dimension. For example, surface plots map surface height to color. The color limits control the limits of the color dimension in a way analogous to setting axis limits.

The axes CLim property controls the mapping of image, patch, and surface CData to the figure colormap. CLim is a two-element vector [cmin cmax] specifying the CData value to map to the first color in the colormap (cmin) and the CData value to map to the last color in the colormap (cmax).

When the axes CLimMode property is auto, MATLAB® sets CLim to the range of the CData of all graphics objects within the axes. However, you can set CLim to span any range of values. This enables individual axes within a single figure to use different portions of the figure's colormap. You can create colormaps with different regions, each used by a different axes.

See the caxis command for more information on color limits.

Simulating Multiple Colormaps in a Figure

Suppose you want to display two different images in the same figure. Images typically have their own colormaps, but you can specify only one colormap per figure. The solution is to concatenate the two colormaps and then setting the CLim property of each axes so that the two images map into different portions of the colormap.

This example displays two images in one figure and maps the data in each image to the appropriate sections of the colormap, which has been created by concatenating the two colormaps together. The colorbar below the two images shows the entire colormap.

Complete Example Code

If you are using the MATLAB Help browser, you can:

Calculating Color Limits

The key to this example is calculating values for CLim that cause each surface to use the section of the colormap containing the appropriate colors.

To calculate the new values for CLim, you need to know

  • The total length of the colormap (CmLength)

  • The beginning colormap slot to use for each axes (BeginSlot)

  • The ending colormap slot to use for each axes (EndSlot)

  • The minimum and maximum CData values of the graphic objects contained in the axes. That is, the values of the axes CLim property determined by MATLAB when CLimMode is auto (CDmin and CDmax).

First, define subplot regions and plot the surfaces.

im1 = load('cape.mat');
im2 = load('flujet.mat');
ax1 = subplot(1,2,1); 
imagesc(im1.X) 
axis(ax1,'image')
ax2 = subplot(1,2,2);
imagesc(im2.X) 
axis(ax2,'image')

Concatenate two colormaps and install the new colormap.

colormap([im1.map;im2.map])

Obtain the data you need to calculate new values for CLim.

CmLength   = length(colormap);   % Colormap length
BeginSlot1 = 1;                  % Beginning slot
EndSlot1   = length(im1.map);    % Ending slot
BeginSlot2 = EndSlot1 + 1; 
EndSlot2   = CmLength;
CLim1      = get(ax1,'CLim');  % CLim values for each axis
CLim2      = get(ax2,'CLim');

Defining a Function to Calculate CLim Values

Computing new values for CLim involves determining the portion of the colormap you want each axes to use relative to the total colormap size and scaling its Clim range accordingly. You can define a MATLAB function to do this.

function CLim = newclim(BeginSlot,EndSlot,CDmin,CDmax,CmLength)
   % 				Convert slot number and range
   % 				to percent of colormap
   PBeginSlot    = (BeginSlot - 1) / (CmLength - 1);
   PEndSlot      = (EndSlot - 1) / (CmLength - 1);
   PCmRange      = PEndSlot - PBeginSlot;
   % 				Determine range and min and max 
   % 				of new CLim values
   DataRange     = CDmax - CDmin;
   ClimRange     = DataRange / PCmRange;
   NewCmin       = CDmin - (PBeginSlot * ClimRange);
   NewCmax       = CDmax + (1 - PEndSlot) * ClimRange;
   CLim          = [NewCmin,NewCmax];
end

The input arguments are identified in the bulleted list above. The function first computes the percentage of the total colormap you want to use for a particular axes (PCmRange) and then computes the CLim range required to use that portion of the colormap given the CData range in the axes. Finally, it determines the minimum and maximum values required for the calculated CLim range and returns these values. These values are the color limits for the given axes.

Using the Function

Use the newclim function to set the CLim values of each axes. The statement

set(ax1,'CLim',newclim(BeginSlot1,EndSlot1,CLim1(1),...
		CLim1(2),CmLength))

sets the CLim values for the first axes so the surface uses color slots 65 to 120. The lit surface uses the lower 64 slots. You need to reset its CLim values as well.

set(ax2,'CLim',newclim(BeginSlot2,EndSlot2,CLim2(1),...
		CLim2(2),CmLength))

How the Function Works

MATLAB enables you to specify any values for the axes CLim property, even if these values do not correspond to the CData of the graphics objects displayed in the axes. The minimum CLim value is always mapped to the first color in the colormap and the maximum CLim value is always mapped to the last color in the colormap, whether or not there are really any CData values corresponding to these colors. Therefore, if you specify values for CLim that extend beyond the object's actual CData minimum or maximum, MATLAB colors the object with only a subset of the colormap.

The newclim function computes values for CLim that map the graphics object's actual CData values to the beginning and ending colormap slots that you specify. It does this by defining a "virtual" graphics object having the computed CLim values.

Was this topic helpful?