Mapping Toolbox

scaleruler

Add graphic scale

Syntax

• scaleruler on 
  scaleruler off
  scaleruler(property,value,...)
  

Background

Cartographers often add graphic elements to the map to indicate its scale. Perhaps the most commonly used is the graphic scale, a ruler-like object that shows distances on the ground at the correct size for the projection.

Description

scaleruler toggles the display of a graphic scale. If no graphic scale is currently displayed in the current map axes, one will be added. If any graphic scales are currently displayed, they will be removed.

scaleruler on adds a graphic scale to the current map axes. Multiple graphic scales can be added to the same map axes.

scaleruler off removes any currently displayed graphic scales.

scaleruler(property,value,...) adds a graphic scale and sets the properties to the values specified.

Examples

Create a map, add a graphic scale with the default settings, and shift it up a bit. Add a second scale showing nautical miles, and change the tick marks and direction.

• worldmap('guatemala','patchonly')
  
  scaleruler
  setm(handlem('scaleruler1'),'YLoc',.205)
  
  scaleruler('units','nm')
  setm(handlem('scaleruler2'),...
       'MajorTick',0:100:300,'MinorTick',0:25:50,...
       'TickDir','down','MajorTickLength',km2nm(20),...
       'MinorTickLength',km2nm(12.5))
  
  
  

Remarks

Graphic scale objects are controlled using setm and getm. A list of graphic scale properties is displayed by the command setm(h), where h is the handle to a graphic scale object. The current values for a displayed graphic scale object can be retrieved using getm. The properties of a displayed graphic scale object can be modified using setm.

Modifying the properties of the graphic scale results in the replacement of the original object. For this reason, handles to the graphic scale object will change. Use handlem('scaleruler') to get a list of the current handles to all graphic scale objects. Use handlem('scalerulerN'), where N is an integer, to get the handle to a particular graphic scale. Use namem to see the names of existing graphic scale objects. The name of a graphic scale object is also stored in the read-only 'Children' property, which is accessed using getm.

Use scaleruler off, clmo scaleruler, or clmo scalerulerN to remove the scale rulers. The handles to the components of the graphic scale are hidden, so using delete will remove only the baseline. In that event, the remaining elements of the graphic scale can be removed with the command delete(findall(gca,'Tag','scalerulerN')), where N is the corresponding integer.

The graphic scale object can be repositioned by dragging the baseline with the mouse. The position can also be changed by modifying the 'XPos' and 'YPos' properties using setm.

Object Properties

Properties that control appearance

Color of the displayed graphic scale -- This property controls the color of the graphic scale lines and text. You can specify a color using a vector of RGB values or one of MATLAB's predefined names. By default, the graphic scale is displayed in black ([0 0 0]).

Angle of the graphic scale label text -- This property controls the appearance of the graphic scale text components. Use any font angle string recognized by MATLAB.

Font family name for all graphic scale labels -- This property sets the font for all displayed graphic scale labels. To display and print properly FontName must be a font that your system supports.

Font size -- A property specifying the font size to use for all displayed graphic scale labels, in units specified by the FontUnits property. The default point size is 9.

Units used to interpret the FontSize property -- When set to normalized, the Toolbox interprets the value of FontSize as a fraction of the height of the axes. For example, a normalized FontSize of 0.16 the text characters to a font whose height is one--tenth of the axes' height. The default units of points are equal to 1/72 of an inch.

Select bold or normal font -- the character weight for all displayed graphic scale labels.

Label text for the graphic scale -- this property contains a string used to label the graphic scale. The text is displayed centered on the scale. The label is often used to indicate the scale of the map, for example "1:50,000,000."

Graphic scale line width -- this property sets the line width of the displayed scale. The value is a scalar representing points, which is 0.5 by default.

Graphic scale major tick locations -- this property sets the major tick locations for the graphic scale. The default values are chosen to give a reasonably sized scale. You can specify the locations of the tick marks by providing a vector of locations. These are usually equally spaced values as generated by start:step:end. The values are distances in the units of the Units property.

Graphic scale major tick labels -- this property sets the text labels associated with the major tick locations. By default, the labels are identical to the major tick locations. These can be overridden by providing a cell array of strings. There must be as many strings as tick locations.

Length of the major tick lines -- this property controls the length of the major tick lines. The length is a distance in the units of the Units property.

Graphic scale minor tick locations -- this property sets the minor tick locations for the graphic scale. The default values are chosen to give a reasonably sized scale. You can specify the locations of the tick marks by providing a vector of locations. These are usually equally spaced values as generated by start:step:end. The values are distances in the units of the Units property.

Graphic scale minor tick labels -- this property sets the text label associated with the minor tick locations. By default, the label is identical to last minor tick location. This can be overridden by providing a string label.

Length of the minor tick lines -- this property controls the length of the minor tick lines. The length is a distance in the units of the Units property.

Style of the graphic scale -- This property selects between three different kinds of graphic scale displays. The default ruler style looks like the MATLAB x-axis. The lines style has three horizontal lines across the tick marks. This type of graphic scale is often used on maps from the U. S. Geological Survey. The patches style has alternating black and white rectangles in place of lines and tick marks.

Direction of the tick marks and text -- This property controls the direction in which the lick marks and text labels are drawn. In the default up direction, the tick marks and text labels are placed above the baseline, which is placed at location given in the XLoc property. In the down position, the tick marks and labels are drawn below the baseline.

Tick locations mode -- This property controls whether the tick locations and labels are computed automatically, or user-specified. Explicitly setting the tick labels or locations results in a 'manual' tick mode. Setting any of the tick labels or locations to an empty matrix resets the tick mode back to 'auto'. Setting the tick mode to 'auto' clears any explicitly specified tick locations and labels, which are then replaced by default values.

X-location of the graphic scale -- this property controls the horizontal location of the graphic scale within the axes. The location is specified in the axes Cartesian projected coordinates. Use showaxes to make the Cartesian grid labels visible. The graphic scale can also be moved by dragging the baseline with the mouse.

Y-location of the graphic scale -- this property controls the vertical location of the graphic scale within the axes. The location is specified in the axes Cartesian projected coordinates. Use showaxes to make the Cartesian grid labels visible. The graphic scale can also be moved by dragging the baseline with the mouse.

Properties that control scaling

Azimuth of scale computation -- The scale of a map varies within the projection, with geographic location and azimuth. This property controls the azimuth along which the scaling between geographic and projected coordinates is computed. The azimuth is given in the current angle units of the map axes. The default azimuth is 0.

Latitude of scale computation -- The scale of a map varies within the projection, with geographic location and azimuth. This property controls the geographic location at which the scaling between geographic and projected coordinates is computed. The latitude is given in the current angle units of the map axes. The default location is the center of the displayed map.

Longitude of scale computation -- The scale of a map varies within the projection, with geographic location and azimuth. This property controls the geographic location at which the scaling between geographic and projected coordinates is computed. The longitude is given in the current angle units of the map axes. The default location is the center of the displayed map.

Planetary radius -- The radius property controls the scaling between angular and surface distances. If radius is a string, then it is evaluated as an almanac body to determine the spherical radius. If numerical, it is the radius of the desired sphere in the same units as the Units property. The default is 'earth'.

Surface distance units -- This property defines the distance units displayed in the graphic scale. Units can be any distance unit string recognized by distdim. The distance string is also used in the last graphic scale text label.

Other Properties

Name string of graphic scale elements -- This property contains the tag string assigned to the graphic elements that comprise the graphic scale. All elements of the graphic scale have hidden handles except the baseline. You do not normally need to access the elements directly.

See Also

distance	Calculates distances between points on a geoid
surfdist	Interactive tool for distance, azimuth and reckoning calculations
axesscale	Resize axes for equivalent scale
paperscale	Figure paper size for a given map scale
distortcalc	Calculates distortion parameters for a map projection
mdistort	Displays contours of constant distortion on a map

rsphere

scatterm