# caxis

## Purpose

Pseudocolor axis scaling.

## Synopsis

    caxis([cmin cmax])
    caxis auto
    v = caxis;
    caxis(caxis)

## Description

`caxis` provides an easy way to manipulate the `CLim` and `CLimMode` properties of axes objects. Pseudocolor plotting functions, such as `mesh`, `surf`, and `pcolor`, create surface and patch objects which map specified color arrays into colormaps to produce color values. This mapping is controlled by the `ColorMap`, `CLim`, and `CLimMode` properties.

`caxis([cmin cmax])` sets the `Clim` color axis scaling parameters to the specified low and high values. Any values in a color array outside the interval `cmin` <= `c` <= `cmax` are clipped; that is, the corresponding patches or pixels are not plotted.

`caxis` `auto`, the default, sets `CLimMode` to indicate that the color axis scaling parameters are computed automatically using the minimum and maximum of the color array specified in the particular pseudocolor plotting function. In this case, only color values set to `Inf` or `NaN` are clipped.

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

`caxis(caxis)` freezes the color axis scaling at the current limits, so that if `hold` is turned on, subsequent plots use the same limits.

## Algorithm

Let `c` be a color array which is the last argument to the `mesh`, `surf`, or `pcolor` function. If `caxis` `auto` is in effect, let `cmin = min(c)` and `cmax = max(c)`. Let `m = length(map)`.

The following linear transformation maps `c` onto `k`, an array of indices in the range `1 <= k <= m`, with `c = cmin` mapping to `k = 1` and `c = cmax` mapping to `k = m`.

If `cmin <= c < cmax`, then

    k = fix((c-cmin)/(cmax-cmin)*m)+1.

If `c == cmax`, then

    k = m.

If `c < cmin,c > cmax,` or `c == NaN`, then

    k = 'invisible'.

## Examples

To obtain`(X,Y,Z)` data for a sphere of radius 1, enter

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

In this case, values of `C` have the range [-1 1]. The statement

    surf(X,Y,Z,C)

allows you to see all of the data. Values of `C` near -1 are assigned the lowest values in the color table; values of `C` near +1 are assigned the highest values in the color table.

To map the top half of the sphere to the highest value in the color table, enter:

    caxis([-1 0])

To use only the bottom half of the color table, enter

    caxis([-1 3])

Since the data in `C` only occupy values in the range [-1 1], the colors assigned to `C` come from the lower part of the color table.

The command

    caxis auto

resets axis scaling back to autoranging and you once again see all the colors in the mesh.

    z = caxis

makes `z = [-1 1]`.

## See Also

`axes`, `axis`, `colormap`, `get`, `set`

The `CLim` and `CLimMode` properties of `axes` objects.

The `ColorMap` property of figure objects.

(c) Copyright 1994 by The MathWorks, Inc.