clickz

Easily get z values of pcolor or image plots from mouse clicks.

Sometimes I plot a pcolor or image plot and I want to know with some precision what values exist a specific locations. The Data Cursor tool in the figure window does not return z values for pcolor plots, so I end up with my eyes darting back and forth between the location of interest in the pcolor plot and the colorbar, trying to pin down the z value at the interesting location.
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.

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.

Syntax
clickz
clickz(N)
clickz(...,ax)
clickz(...,'keep')
clickz(,...'TextProperty',TextValue)
z = clickz(...)
[x,y,z] = clickz(...)
[x,y,z,h] = clickz(...)

Description
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.