ColorScale

ColorScale [flags] [, keyword = value, ...] [axisLabelStr ]

The ColorScale operation adds a color scale (or "color legend") annotation a graph, Gizmo plot or page layout. For background information, see Color Scales.

The ability to add colorscales to a Gizmo plot was added in Igor Pro 8.00.

The ColorScale operation can be executed with no flags and no parameters. It acts on the current target window or the active subwindow or on the window or subwindow specified by the /W flag.

When the target is a graph, the color scale represents the colors and values associated with the first image plot that was added to the graph. If there is no image plot in the graph, the color scale represents the first contour plot or first f(z) trace added to the graph, one of which must exist for the command to execute without error when executed without parameters.

When the target is a Gizmo plot, the color scale represents the colors and values associated with the first surface object, preferring the surface fill color table over the surface gridlines color table. If there is no such surface object, the color scale represents the first scatter object using a color table. If there is no such scatter object, the color scale represents the first path object using a color table. If there is no such path object, the color scale represents the first ribbon object using a color table.

Executing ColorScale with no parameters when the target is a page layout displays a color bar as if the ctab={0,100,Rainbow} parameters had been specified.

Flags

Use the /W=win flag to specify a specific graph or layout window. When used on the command line or in a Macro or Proc, /W must precede all other flags.

To change a color scale, use the /C/N=name flags. Annotations are automatically named "text0", "text1", etc if no name is specified when it is created, and you must use that name to modify an existing annotation or else a new one will be created.

For explanations of all flags see TextBox.

Parameters

The following keyword-value pairs are the important parameters to the ColorScale operation, because they specify what object the color scale is representing.

note

For use with page layouts, the keyword ={graphName,...} form is required.

For graphs it is simpler to use the image=imageInstanceName form (omitting graphName), though you can use $"" to mean the top graph, or specify the name of another graph with the long form. See the examples.

axisLabelStr	Contains text that is printed beside the color scale's main axis. This text is interpreted the same way as for the Label operation.
	Using escape codes you can change the font, size, style and color of text, create superscripts and subscripts, and apply other effects. See Annotation Escape Codes for details.
	You can use the AppendText or ReplaceText operations to modify this axis label string. The default value for axisLabelStr is "".
cindex=cindexMatrixWave
	The colors shown are those in the named color index wave with axis values derived from the wave's X (row) scaling and units.
	The image colors are determined by doing a lookup in the specified matrix wave. See the cindex keyword as used in the ModifyImage operation.
contour=contourInstanceName
contour={graphName,contourInstanceName }
	The colors show the named contour plot's line colors and associated contour (Z) values and contour data units. All of the image plot's characteristics are represented, including color table, cindex, and fixed colors.
	graphName can be just the name of a top-level graph window or a subwindow specification like Panel0#G0. See Subwindow Syntax for details on subwindow specifications.
contourFill=contourInstanceName
contourFill={graphName,contourInstanceName }
	The colors show the named contour plot's fill colors and associated contour (Z) values and contour data units. All of the image plot's characteristics are represented, including color table, cindex, and fixed colors.
	graphName can be just the name of a top-level graph window or a subwindow specification like Panel0#G0. See Subwindow Syntax for details on subwindow specifications.
	The contourFill keyword was added in Igor Pro 8.00.
ctab={zMin,zMax,ctName, reverse }
	The color table specified by ctName is drawn in the color legend. ctName can be any of those returned by the CTabList function, such as Grays or Rainbow. Also see Color Tables.
	The color table name can be omitted if you want to leave it unchanged. zMin and zMax set the range of Z values to map. Set parameter mode to 1 to reverse the color table; zero or missing value does not reverse the color table.
	The color table specified by ctName is drawn in the color legend.
	zMin and zMax set the range of Z values to map.
	The color table name can be omitted if you want to leave it unchanged.
	ctName can be any color table name returned by the CTabList function, such as Grays or Rainbow (see Color Tables) or the name of a 3 column or 4 column color table wave (see Color Table Waves).
	A color table wave name supplied to ctab must not be the name of a built-in color table (see CTabList). A 3 column or 4 column color table wave must have values that range between 0 and 65535. Column 0 is red, 1 is green, and 2 is blue. In column 3 a value of 65535 is fully opaque and 0 is fully transparent.
	Set reverse to 1 to reverse the color table. Setting it to 0 or omitting it leaves the color table order unreversed.
image=imageInstanceName
image={graphName,imageInstanceName }
	The colors show the named image plot's colors and associated image (Z) values and image data units. All of the image plot's characteristics are represented, including color table, cindex, lookup wave, eval colors, and NaN transparency.
	note Only false-color image plots can be used with ColorScale (see Indexed Color Details).
	graphName can be just the name of a top-level graph window or a subwindow specification like Panel0#G0. See Subwindow Syntax for details on subwindow specifications.
logLabel=t	t is the maximum number of decades before minor tick labels are suppressed. The default value is 3.
	The logLabel keyword was added in Igor Pro 7.00.
logTicks=t	t=0 means "auto". This is the default value.
	If t is not 0 then it represents the maximum number of decades before minor ticks are suppressed.
	The logTicks keyword was added in Igor Pro 7.00.
lookup=waveName	Specifies an optional 1D wave that is used to modify the mapping of scaled z values into the color table specified with the ctab keyword. Values should range from 0.0 to 1.0. A linear ramp from 0 to 1 would have no effect while a ramp from 1 to 0 would reverse the image. Used to apply gamma correction to grayscale images or for special effects. Use lookup=$"" to remove option.
	This keyword is not needed with the image keyword, even if the image plot uses a lookup wave. The image plot's lookup wave is used instead of the ColorScale lookup wave.
path=gizmoObjectSpec
path={gizmoName, gizmoObjectSpec}
	The colors show the named Gizmo path plot's colors and associated X, Y, or Z values and units. Only the path plot's color table is represented. Other color modes such as color wave or solid colors are not supported.
	gizmoName can be just the name of a top-level Gizmo window or a subwindow specification like Panel0#GZ0. See Subwindow Syntax for details on subwindow specifications.
	gizmoObjectSpec can be just the name of the object like path0, or a colon-separated path to the object in a group like group0:path0. Unlike ModifyGizmo setCurrentGroup, gizmoObjectSpec does not start with the name of the Gizmo window.
	The path keyword was added in Igor Pro 9.00.
ribbon=gizmoObjectSpec
ribbon={gizmoName, gizmoObjectSpec}
	The colors show the named Gizmo ribbon plot's colors and associated X, Y, or Z values and units. Only the ribbon plot's color table is represented. Other color modes such as color wave or solid colors are not supported.
	See the path keyword for {gizmoName, gizmoObjectSpec} details.
	The ribbon keyword was added in Igor Pro 9.00.
scatter=gizmoObjectSpec
scatter={gizmoName, gizmoObjectSpec}
	The colors show the named Gizmo scatter plot's marker colors and associated X, Y, or Z values and units. Only the scatter plot's color table is represented. Other color modes such as color wave or solid colors are not supported.
	See the path keyword for {gizmoName, gizmoObjectSpec} details.
	The scatter keyword was added in Igor Pro 9.00.
surface=gizmoObjectSpec
surface={gizmoName, gizmoObjectSpec }
	The colors show the named Gizmo surface plot's grid line colors and associated surface X, Y, or Z values and surface matrix units. Unlike image plots, only the surface plot's color table is represented. Other color modes such as color wave or solid colors are not supported.
	See the path keyword for {gizmoName, gizmoObjectSpec} details.
	The surface keyword was added in Igor Pro 8.00.
surfaceFill=gizmoObjectSpec
surfaceFill={gizmoName, gizmoObjectSpec }
	The colors show the named Gizmo surface plot's fill colors and associated surface X, Y, or Z values and surface matrix units. Unlike image plots, only the surface plot's color table is represented. Other color modes such as color wave or solid colors are not supported.
	gizmoName can be just the name of a top-level Gizmo window or a subwindow specification like Panel0#GZ0. See Subwindow Syntax for details on subwindow specifications.
	See the path keyword for {gizmoName, gizmoObjectSpec} details.
	The surfaceFill keyword was added in Igor Pro 8.00.
trace=traceInstanceName
trace={graphName,traceInstanceName }
	The colors show the color(s) of the named trace. This is useful when the trace has its color set by a "z wave" using the ModifyGraph zColor(traceName)=... feature. In the Modify Trace Appearance dialog this is selected in the "Set as f(z)" subdialog. The color scale's main axis shows the range of values in the z wave, and displays any data units the wave may have.
	graphName can be just the name of a top-level graph window or a subwindow specification like Panel0#G0. See Subwindow Syntax for details on subwindow specifications.

Size Parameters

The following keyword-value parameters modify the size of the color scale annotation. These keywords are similar to those used by the Slider control. The size of the annotation is indirectly controlled by setting the size of the "color bar" and the various axis parameters. The annotation sizes itself to accommodate the color bar, tick labels, and axis label(s).

height=h	Sets height of color bar in points, overriding any heightPct setting. The default height is 75% of the plot area height if the color scale is vertical, or a constant of 15 points if the color scale is horizontal. The default is restored by specifying height=0. Specifying a heightPct value resets height to this default.
heightPct=hpct	Sets height as a percentage of graph's plot area, overriding any height setting. The default height is 75% of the plot area height if the color scale is vertical, or a constant of 15 points if the color scale is horizontal. The default height is restored by setting heightPct=0.
side=s	Selects on which axis to draw main axis ticks.
	s =1: Right of the color bar if vert=1, or below if vert=0. s =2: Left of the color bar if vert=1, or above if vert=0.
vert=v	Specifies orientation of color scale.
	v =0: Horizontal. v =1: Vertical (default).
width=w	Sets width of color bar in points, overriding any widthPct setting. The default width is a constant 15 points if the color scale is vertical, or 75% of the plot area width if the color scale is horizontal. The default is restored by specifying width=0. Specifying a widthPct value resets width to this default.
widthPct=wpct	Sets width as a percentage of graph's plot area, overriding any width setting. The default width is a constant 15 points if the color scale is vertical, or 75% of the plot area width if the color scale is horizontal. The default is restored by setting widthPct=0. Specifying a width value resets widthPct to this default.

Color Bar Parameters

The following keyword-value parameters modify the appearance of the color scale color bar.

colorBoxesFrame=on	Draws frames surrounding up to 99 swatches of colors in the color bar (on =1).
	When specifying more than 99 colors in the color bar (such as the Rainbow color table, which has 100 colors), the boxes aren't framed. Framing color boxes is effective only for small numbers of colors. Set the width of the frame with the frame keyword.
	Use on =0 to turn off color box frames.
frame=f	Specifies the thickness of the frame drawn around the color bar in points (f can range from 0 to 5 points). The default is 1 point. Fractional values are permitted.
	Turn frames off with f =0. Values less that 0.5 do not display on screen, but the thin frame will print.
frameRGB=(r,g,b[,a]) or 0
	Sets the color of the frame around the color bar. r, g, b, and a specify the the color and optional opacity as RGBA Values. The frame includes the individual color bar colors when colorBoxesFrame=1.
	The frame will use the colorscale foreground color, as set by the /G flag, when frameRGB=0.

Axis Parameters

The following keyword-value parameters modify the appearance of the color scale axes. These keywords are based on the ModifyGraph for Axes keywords because they modify the main or secondary color scale axes.

axisRange={zMin, zMax }
	Sets the color bar axis range to values specified by zMin and zMax. Use * to use the default axis range for either or both values.
	Omit zMin or zMax to leave that end of the range unchanged. For example, use {zMin, } to change zMin and leave zMax alone, or use { ,*} to set only the axis maximum value to the default value.
dateInfo={sd,tm,dt }	Controls formatting of date/time axes.
	sd=0: Show date in the date&time format. The date is always suppressed if tm=2 (elapsed time). The time is always suppressed if there are fewer than one ticks per day and tm=0 (12-hour time) or tm=1 (24-hour time). sd=1: Suppress date. The date is always suppressed if tm=2 (elapsed time). sd=2: Suppress time. The time is always shown if tm=2 (elapsed time). sd=2 requires Igor Pro 9.00 or later. tm=0: 12 hour (AM/PM) time. tm=1: 24 hour (military) time. tm=2: Elapsed time. dt=0: Short dates (2/22/90). dt=1: Long dates (Thursday, February 22, 1990). dt=2: Abbreviated dates (Thurs, Feb 22, 1990).
	These have no effect unless the axis is controlled by a wave with 'dat' data units.
	These date formats do not work with dates before 0001-01-01 in which case the axis displays an empty string. You can apply custom date formats using the dateFormat keyword in such cases.
	To use a custom date format as specified by the dateFormat keyword, you must specify -1 for the dt parameter to dateInfo.
	For an f(z) color scale:
	SetScale d, 0,0, "dat", fOfZWave
	For a contour plot or image plot color scale:
	SetScale d, 0,0, "dat", ZorXYZorImageWave
	See Date/Time Axes and Date, Time, and Date&Time Units for details on how date/time axes work.
font=fontNameStr	Name of font as string expression. If the font does not exist, the default font is used. Specifying "default" has the same effect. Unlike ModifyGraph, the fontName is evaluated at runtime, and its absence from the system is not an error.
fsize=s	s =0: use the default (graph) font size for tick labels and axis label(s).
	s is the font size in points. The default is 0 (auto font size).
fstyle=fs	Specifies the font style. fs is a bitwise parameter with each bit controlling one aspect of the font style for the tick mark labels as follows:
	Bit 0: Bold Bit 1: Italic Bit 2: Underline Bit 4: Strikethrough
	See Setting Bit Parameters for details about bit settings.
highTrip=h	If the extrema of an axis are between its lowTrip and its highTrip then tick mark labels use fixed point notation. Otherwise they use exponential (scientific or engineering) notation. The default highTrip is 100,000.
lblLatPos=p	Sets a lateral offset for the main axis label. This is an offset parallel to the axis. p is in points. Positive is down for vertical axes and to the right for horizontal axes. The default is 0.
lblMargin=m	Moves the main axis label by m points (default is 0) from the normal position. The default value is -5, which brings the axis label closer to the axis. Use more positive values to move the axis label away from the axis.
lblRot=r	Rotates the main axis label by r degrees counterclockwise starting from the normal label orientation. r is a value from -360 to 360.
log=l	Specifies the axis type.
	l =0: Linear (default). l =1: Log base 10. l =2: Log base 2.
logHTrip=h	Same as highTrip but for log axes. The default is 10,000.
logLTrip=l	Same as lowTrip but for log axes. The default is 0.0001.
logTicks=t	t is maximum number of decades in log axis before minor ticks are suppressed.
lowTrip=l	If the extrema of an axis are between its lowTrip and its highTrip then tick mark labels use fixed point notation. Otherwise they use exponential (scientific or engineering) notation. The default lowTrip is 0.1.
minor=m	m =0: Disables minor ticks (default). m =1: Enables minor ticks.
notation=n	n =0: Engineering notation (default). n =1: Scientific notation.
nticks=n	n is the approximate number of ticks to be distributed along the main axis. Ticks are labelled using the same automatic algorithm used for graph axes. The default is 5.
	n =0:
prescaleExp=exp	Multiplies axis range by 10^exp for tick labeling and exp is subtracted from the axis label exponent. In other words, the exponent is moved from the tick labels to the axis label. The default is 0 (no modification). See the discussion in ModifyGraph's Details section.
tickExp=te	te =1 forces tick labels to exponential notation when labels have units with a prefix. te =0 turns this off.
tickLen=t	Sets the length of the ticks. t is the major tick mark length in points. This value must be between -100 and 50.
	t = 0 to 50: Draws tick marks between the tick labels and the colors box. t =-1: Auto tick length (default), equal to 70% of the tick label font size. Draws tick marks between the tick labels and the colors box. t =-2 to -50: Draws tick marks crossing the edge of the colors box nearest the tick labels. The actual total tick mark length is -t. t =-100 to -51: Draws tick marks inside the edge of the colors box nearest the tick labels. Actual tick mark length is -(t +50). For example, -58 makes an inside tick mark that is 8 points long.
tickThick=t	t is the tick mark thickness in points (from 0 to 5 points). The default is 1 point. Fractional values are permitted.
	t =0 turns tick marks off, but not the tick labels.
tickUnit=tu	tu =1: suppresses units labels attached to tick marks. tu =0: turns units labels back on.
userTicks={tvWave,tlblWave }
	Supplies user defined tick positions and labels for the main axis. TvWave contains the numeric tick positions while text wave tlblWave contains the corresponding labels.
	Overrides normal ticking specified by nticks.
	See User Ticks from Waves for details.
	The tick mark labels can be multiline and use styled text. For more details, see Fancy Tick Mark Labels.
ZisZ=z	z =1 labels the zero tick mark label (if any) as the single digit "0" regardless of the number of digits used for other labels. Default is z=0.

Secondary Axis Parameters

axisLabel2=axisLabelString2
	Axis label for the secondary axis. This axis label is drawn only if userTicks2 is in effect. Text after any \r character is ignored, as is the \r character. The default is "".
lblLatPos2=p	Sets a lateral offset for the secondary axis label. This is an offset parallel to the axis. p is in points. Positive is down for vertical axes and to the right for horizontal axes. The default is 0.
lblMargin2=m	m is distance in points (default 0) to move the secondary axis label from the position that would be normal for a graph. The default is value is -5, which brings the axis label closer to the axis. Use more positive values to move the axis label away from the axis.
lblRot2=r	Rotates the secondary axis label by r degrees counterclockwise starting from the normal label orientation. r is a value from -360 to 360.
userTicks2={tvWave,tlblWave }
	Supplies user defined tick positions and labels for a second axis which is always on the opposite side of the color bar from the main axis. The tick mark labels can be multiline and use styled text. For more details, see Fancy Tick Mark Labels. This is the only way to draw a second axis.

Image Plot ColorScale Example

Make/O/N=(20,20) img=p*q; NewImage img              // Make and display an image
ColorScale                                          // create default color scale
ColorScale/C/N=text0 nticks=3,minor=1,"Altitude"    // first annotation is text0
ModifyImage img ctab= {*,*,Relief19,0}              // 19-color color table
ColorScale/C/N=text0 axisRange={100,300}            // Detail for 100-300 range
ColorScale/C/N=text0 colorBoxesFrame=1              // Frame the color boxes
ColorScale/C/N=text0 frameRGB=(65535,0,0)           // Red frame

Gizmo Plot ColorScale Example

Window GizmoDemo() : GizmoPlot
	PauseUpdate; Silent 1
	// Building Gizmo 7 window...
	NewGizmo/W=(35,45,435,353)
	ModifyGizmo startRecMacro=700
	ModifyGizmo scalingOption=63
	AppendToGizmo Surface=root:img,name=surface0
	ModifyGizmo ModifyObject=surface0,objectType=surface,property={ srcMode,0}
	ModifyGizmo ModifyObject=surface0,objectType=surface,property={ surfaceCTab,CyanMagenta}
	AppendToGizmo Axes=boxAxes,name=axes0
	ModifyGizmo ModifyObject=axes0,objectType=Axes,property={-1,axisScalingMode,1}
	ModifyGizmo ModifyObject=axes0,objectType=Axes,property={-1,axisColor,0,0,0,1}
	ModifyGizmo ModifyObject=axes0,objectType=Axes,property={0,ticks,3}
	ModifyGizmo ModifyObject=axes0,objectType=Axes,property={1,ticks,3}
	ModifyGizmo ModifyObject=axes0,objectType=Axes,property={2,ticks,3}
	ModifyGizmo modifyObject=axes0,objectType=Axes,property={-1,Clipped,0}
	ModifyGizmo setDisplayList=0, object=surface0
	ModifyGizmo setDisplayList=1, object=axes0
	ModifyGizmo autoscaling=1
	ModifyGizmo currentGroupObject=""
	ModifyGizmo showInfo
	ModifyGizmo infoWindow={551,23,1368,320}
	ModifyGizmo endRecMacro
	ModifyGizmo SETQUATERNION={0.531194,-0.220652,-0.320213,0.752734}
	ColorScale/C/N=text0/X=2.75/Y=20.45 surfaceFill=surface0
EndMacro

See Also

For all other flags see TextBox and AppendText operations.

Color Scales, AnnotationInfo, AnnotationList

Demo

Open ColorScale Demo