The image pseudo object (Intensity map)

Before getting much farther in this section, you should try running the picplot.m and pltmap.m programming examples so that you have a better context for the information that follows. The julia application (in the math folder) is another good example of the use of the image pseudo object.

The intensity map pseudo object (sometimes called the image pseudo object) provides cursoring methods appropriate for this object type and also includes several optional components including:

A color bar that serves as a legend for the z-axis values as well as provides a method of changing the colormap used to represent the z data.
A slider (labeled 'edge') that allows you to control how wide a range around a midpoint is used when determining the color used to represent each array element.
A slider (labeled ''mid'') that allows you to control the center value of the range of values used to determine the color for each array element.
A checkbox that allows you to control the visibility of the axis gridlines.
A 'view all' button, that when clicked on resets the axis limits associated with the image object so that the entire image data set is visible. A secondary feature of this button is activated by right-clicking on it instead, however, the right-click action is different depending on whether the Zout (zoom out) tag exists in the associated menu box. If this tag does not exist, then each time you right-click on the view all button the axis limits are zoomed in to expose only the middle 36% of the visible area. (This represents a 60% expansion of both the x and y axes.). However, if the Zout tag exists then the right-click action described above is not needed since it would duplicate the right-click action of the Zout tag. So in that case, right-clicking on the view all button saves the current image axis limits into an application variable of the axis called ilim. From that point on (or until you right click the view all button again), the left-click action of the view all button will set the axis limits according to the data saved in the ilim application data. This means that the right-click action essentially redefines what we mean by "all the data", when we select "view all".

Initialization

h = plt('image',axI,x,y,z,opt);
The image object is created in an axis and figure that must be created beforehand using the plt pseudo object. For example, suppose we create a figure with the command plt(x1,y1,x2,y2,'Subplot',[40 60]); This creates two axes, the smaller one (40% of the height) below and the larger one on top. And suppose we want to put the intensity map in the larger axis, then we would use plt('image',2,x,y,z);. I have set axI equal to 2 to indicate that the image should be inserted into the upper plot (using the usual rules for the ordering of the axes). You wouldn't expect it matters what is in x2,y2 since this trace is covered over by the image object, but in fact, x2 should be set to the same array as the x vector specified in the image initialization. This ensures that the intensity map cursors operate correctly. (The data in y2 on the other hand does not matter as long as it is the same length as x2).

opt is an optional cell array that specifies the image object options. This cell array may contain any or all of the following strings in the following table. These strings are case insensitive, and actually, all characters except the first one are ignored. So for example 'view', 'ViewAll', and 'V' would all serve the same purpose.

'cbar'	If this string is included the color bar image is created which serves as a color key (i.e. for displaying the current color map). You can click on this color bar to cycle through ten different color maps as follows: 0: jet 5: colorcube 1: rainbow 6: lines 2: sometric 7: hot 3: seismic 8: cool 4: gray 9: winter This entry is an exception to the rule that only the first character is significant, because you may also include a digit between 0 and 6 as the last character of the string. This specifies which color map to appear when the image object is initialized. For example 'cbar3', 'c3' or 'CbarSeismic3' all would initialize the color map to "seismic". If the last character of the string is not a digit then the the rainbow color map is selected as the default.
'edge'	If this string is included the "edge" slider will appear which controls the range of the zData that is mapped to the selected color map.
'mid'	If this string is included, the "mid" slider will appear which controls the midpoint of the zData range that is mapped to the selected color map. The effect of adjusting this slider, as well as the "edge" slider mentioned above, is described in more detail near the end of this page under the heading Edge and Mid sliders.
'grid'	If this string is included, a "grid" checkbox will appear which allows you to turn the grid lines for the image object on or off. This is an exception to the rule that the case is insensitive since 'Grid' and 'grid' have slightly different meanings. They both create the checkbox, but the capitalized version initializes the check box to 'on' (i.e. the grid lines are enabled) and the lowercase version initializes the box to 'off'.
'view'	If this string is included a "view all" button will appear which when left-clicked on will zoom the axis so that the entire image data set is visible. As mentioned above, you may also zoom into the middle of the visible region by right-clicking on this button. (The middle 60% of both the x and y axes will become visible.)
'direct'	Normally the z data is scaled so that the full range of the color map is used. That is, the smallest value in the z data is mapped to the first color of the colormap, and the largest value in the z data is mapped to the last color of the colormap. Sometimes you may only want to use a portion of the colormap. To do this, include 'direct' (or 'd') in the options list. This causes a 1 in the z data to map to the first colormap color and an n in the z data to map to the nth colormap color. Usually, the last colormap color is achieved when z = 64 or z = 256, although actually a colormap can have any length.

You may optionally include a 4-element position vector (in normalized coordinates) after any of these option strings except the last one ('direct'). If the position vector is not included, then a default position is chosen for the item. For example:

opt = {'Cbar' [.5 .4 .02 .24] 'Grid' 'ViewAll' [.91 .75 .04 .02]};

When this option cell array is used for the image object initialization, a color bar, a grid checkbox, and a view all button will be created, but the edge and mid sliders will not be since they are not included in the options list. The color bar and view all button will be positioned at the coordinates given, whereas the grid checkbox will be positioned at its default location since there is no position specified for it in the options list. You may use a space or comma as a delimiter between option elements (i.e. row vector form as in the above), or you may use semicolons if you prefer (i.e. column vector form).

Image update commands

The call that initializes the pseudo image object returns the image handle h which you may then use in any of the image modification commands shown below. First, we have the data update commands which come in seven forms depending on which coordinates you want to update:

   plt('image',h,'x',x);
   plt('image',h,'y',y);
   plt('image',h,'z',z);
   plt('image',h,'xy',x,y);
   plt('image',h,'xz',x,z);
   plt('image',h,'yz',y,z);
   plt('image',h,'xyz',x,y,z);

Then we also have the following commands to change the values of the mid and edge sliders (if they were created during the image initialization), the x or y limits, and the color map:

   plt('image',h,'mid',Value);
   plt('image',h,'edge',Value);
   plt('image',h,'xlim',[xLower xUpper]);
   plt('image',h,'ylim',[yLower yUpper]);
   plt('image',h,'cbar',mapNumber);

In the last command above, mapNumber is usually number between 0 and 9 specifying one of the 10 colormaps listed in the table above in the initialization section. However, you may also use this command to specify new colormaps. For example, the command:

plt('image',h,'cbar',{'Negative',flipud(colormap('gray'))});

will create a new colormap called 'Negative' and makes that colormap active. Now suppose we create yet another colormap using the command:

plt('image',h,'cbar',{'Noise',rand(256,3)});

Now as you left or right click on the colorbar next to the image, the colormap will rotate among 12 different colormaps instead of just the 10 colormaps defined by default. Also, we could use the commands:

plt('image',h,'cbar',10);
plt('image',h,'cbar',11);

to switch to the 'Negative' and 'Noise' colormaps respectively. The colormap selections will revert back to the 10 default colormaps when Matlab is closed and restarted. If you want to revert to the default colormap set in the current Matlab session, you could do that with the command:

setappdata(0,'cmaps',[]);

Finally, the last two image update commands are:

plt('image',h,'direct',1);
plt('image',h,'direct',0);

The first one selects the direct scaling for the z data (mentioned above in the initialization section) and the second one reverts to the usual z data scaling that is selected by default.

For convenience, you can combine any of the above image modification commands into a single command. For example to change the y and z data values, adjust the edge slider and the y-axis limits, and switch to the seismic colormap with direct scaling, you would use a command such as:

plt('image',h,'yz',y,z,'edge',1.5,'ylim',[0 5],'direct',1,'cbar',3);

Image data editing

Editing of image data is described near the end of the Data editing section under the heading 3d data editing

Mid and Edge sliders

These sliders were designed for situations where the z data has an approximately Gaussian distribution. They can also work with other distributions but not if the z data is bimodal or highly skewed. In those cases using these sliders will produce confusing results. Suppose these sliders are enabled and set to their default startup values (mid = 0, edge = 1). Then the axis clim values will be set to [μ - σ, μ + σ] where μ and σ are the mean and standard deviation of the current z data values. (Past z data values do not influence μ or σ). This means that approximately 68% of the data will influence the color choice for each pixel. All the z values below clim(1), about 16% of the data, will map to the first color in the colormap and all the z values above clim(2), also about 16% of the data, will map to the last color in the colormap. If you change the edge slider to 2, then the clim vlaues will be set to [μ - 2σ, μ + 2σ] and so 2 standard deviations of data are represented, and the tails (now each representing 2.5% of the data) will map to the first and last colors of the colormap. The advantage of using smaller values of edge is that you can see the effects of smaller variations in the z data in the image, but the disadvantage is that variations in the tails of the distribution will not be noticeable at all.

If we leave the edge slider set to 2 and then bump the mid slider from 0 to 0.1, the clim values will be set to [μ - 1.9σ, μ + 2.1σ]. This makes the lower tail somewhat bigger and the upper tail somewhat smaller. We increase the mid slider when the data larger than the mean is more interesting and we decrease the mid slider when the data smaller than the mean is more interesting. The general formula for the clim values is: [μ - (edge+mid)σ, μ + (edge-mid)σ].

Whenever new z data is loaded into the image, the following 4 element row vector is computed and saved in the image object's user data: [μ σ min(z(:)) max(z(:))].

The first two values are used by the mid and edge sliders to set the clim values, except for the special case where the edge slider is set to zero. In that case clim is set to the last two values in the user data vector.

The 4 element user data vector may also be used by a program to set the clim property or for other purposes (see the pltmap.m demo program as an example of this).