MATLAB Examples

clickz documentation

This function temporarily prints z values corresponding to clicked points on a surface or image. If multiple surfaces or images exist in the same axes, clickz first looks for surfaces and determines the one on the top of the graphical stack is the relevant one. If no surfaces exist, but an image or multiple images exist, clickz probes the image on the top of the graphical stack.

To find "z" values of an existing image or pcolor plot, simply type clickz and start clicking on areas of interest. Instead of clicking, you may also hit any key on the keyboard except the keys listed below which perform the following functions:

  • Carriage return terminates data entry.
  • + or z zooms in, centered on current cursor location.
  • - or x zooms out, centered on current cursor location.

Above I put "z" in quotation marks for a reason. This function does not actually return plotted z values, but it probes the color data of surfaces and images and assumes color corresponds to z values. This is often true, but not always. For example, you may have some x,y,z data plotted as a surface and you're letting cdata represent some other variable. Accordingly, this function is probably best used with 2D pcolor or image plots, although it can sometimes be used with 3D surface plots.

Occasionally, linear interpolation between plotted data points fails, such as when xdata and ydata are not perfectly monotonic and plaid. I've only run into this problem when plotting polar stereographic data referenced one latitude, onto a polar stereographic map referenced to another latitude. If for some reason linear interpolation fails, clickz will attempt to find the nearest x,y data points by Euclidean distance, and will print z data at that nearby location. In such a case, any output x,y,z data will reflect the nearby point instead of the clicked point.



z = clickz(...)
[x,y,z] = clickz(...)
[x,y,z,h] = clickz(...)


clickz temporarily prints a z value on a plot at each click location. Previous printed values are deleted with each new click. clickz continues to run until user hits Return on the keyboard.

clickz(N) performs clickz N times or until the user hits Return on the keyboard. If N is specified with 'keep' and/or text formatting, N must be the first input argument.

clickz(...,ax) specifies an axis handle ax on which to use clickz.

clickz(...,'keep') does not delete printed points.

clickz(,...'TextProperty',TextValue) formats printed text. Multiple text properties and values may be specified, including fontsize, color, background, etc.

z = clickz(...) returns an array of clicked z values.

[x,y,z] = clickz(...) returns clicked x, y, and z values.

[x,y,z,h] = clickz(...) also returns text object handle h when the 'keep' command is used and all four outputs are requested by the user.


Suppose you have this plot:

shading interp

Upon inspection you may say, "Wow, what's the value at that interesting light blue spot near (x=14,y=26)?" To answer this, you might look at the colorbar and your eyes will dart back and forth between the image and the colorbar, trying to narrow in on where exactly the light blue of (x=14,y=26) lies on the colorbar.

Then, if you're like me, you'll start second-guessing your ability to distinguish between colors on that smooth gradient. So you might try clicking the Data Cursor tool in the Figure Window, which will in turn tell you that X:14, Y:26, Z:0. That's because Matlab hasn't plotted this colormap in vertical z space--despite the fancy colors, the whole surface lies in the z=0 plane.

The next trick I sometimes try is to start setting caxis limits. By inspection I can see that the light blue lies somewhere between -4 and -1, so I might try

caxis([-4 -1])

and then I see that the interesting point is probably between -3.5 and -2.5, and I can keep narrowing the caxis limits from there to hone in on the actual value by inspecting the colors. So

caxis([-3.5 -2.5])

begins to show that the plotted z value at (x=14,y=26) is about -3. But why go through all that trouble? Let's get back to our original case by resetting caxis limits:

caxis auto

Instead of iteratively adjusting caxis limits, you could simply type


and click on the interesting spot.

If you know you want 5 spots before you start clicking, type this:


If you want the text to be blue, this does the trick:


If you don't want the printed values to disappear, use the 'keep' command:


To return arrays of clicked x,y,z values, tell clickz that you want data like this:

[x,y,z] = clickz;

Author Info

This function and supporting documentation were written by Chad A. Greene of the University of Texas at Austin's Institute for Geophysics (UTIG), December 2014. The clickz function includes John D'Errico's inpaint_nans function.