scaleruler

Add or modify graphic scale on map axes

Syntax

scaleruler
scaleruler on
scaleruler off
scaleruler(property,value,...)
h = scaleruler(...)


Description

scaleruler toggles the display of a graphic scale. If no graphic scale is currently displayed in the current map axes, one is added. If any graphic scales are currently displayed, they are 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. You can display a list of graphic scale properties using 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.

h = scaleruler(...) returns the hggroup handle to the graphic scale object.

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.

Examples

Add Graphic Scale to Map Axes

Create a map display of Florida.

usamap('Florida')
geoshow('usastatelo.shp','FaceColor','yellow')

Add a graphic scale. Change the location of the scale by setting the XLoc and YLoc properties. Specify tick locations using the MajorTick property.

scaleruler on
setm(handlem('scaleruler1'), ...
    'XLoc',-3.21e5,'YLoc',2.81e6, ...
    'MajorTick',0:200:600)

Add a second graphics scale that shows distance in nautical miles. Change the direction of the tick marks and text by setting the TickDir property.

scaleruler('units','nm')
setm(handlem('scaleruler2'), ...
    'XLoc',-3.2e5, ...
    'YLoc',2.78e6, ...
    'TickDir','down', ...
    'MajorTick',0:100:300, ...
    'MinorTick',0:25:50, ...
    'MajorTickLength',km2nm(25),...
    'MinorTickLength',km2nm(12.5))

Customize Appearance of Graphic Scale

Create a map of Texas and the surrounding states. Your map might look different because the polcmap function randomizes colors.

states = readgeotable("usastatehi.shp");
figure
usamap("Texas")

h = height(states);
faceColors = makesymbolspec("Polygon",...
    {'INDEX',[1 h],'FaceColor',polcmap(h)});

geoshow(states,"DisplayType","polygon", ...
    "SymbolSpec",faceColors)

Add a default graphic scale. Change the location and set the font size to 8 points.

scaleruler on
setm(handlem("scaleruler1"), ...
    "XLoc",-6.2e5,"YLoc",3.1e6, ...
    "MajorTick",0:200:600, ...
    "FontSize",8)

The location units of scaleruler default to kilometers. Note that handlem accepts the keyword "scaleruler" or "scaleruler1" for the first scaleruler, "scaleruler2" for the second one, etc. If there is more than one scaleruler on the current axes, specifying the keyword "scaleruler" returns a vector of handles.

Return the scaleruler as a Group object using the handlem function. Inspect its properties using the getm function.

s = handlem("scaleruler");
getm(s)

ans = struct with fields:
            Azimuth: 0
           Children: []
              Color: [0 0 0]
          FontAngle: 'normal'
           FontName: 'Helvetica'
           FontSize: 8
          FontUnits: 'points'
         FontWeight: 'normal'
              Label: ''
                Lat: 29.6479
               Long: -101.7263
          LineWidth: 0.5000
          MajorTick: [0 200 400 600]
     MajorTickLabel: {4x1 cell}
    MajorTickLength: 20
          MinorTick: [0 25 50 75 100]
     MinorTickLabel: '100'
    MinorTickLength: 12.5000
             Radius: 'earth'
         RulerStyle: 'ruler'
            TickDir: 'up'
           TickMode: 'manual'
              Units: 'km'
               XLoc: -620000
               YLoc: 3100000
               ZLoc: []

Create a second graphic scale using units of nautical miles. Modify the tick properties of the second graphic scale.

scaleruler("units","nm")
setm(handlem("scaleruler2"),"YLoc",3.0e6, ...
    "MajorTick",0:100:300,...
    "MinorTick",0:25:50,"TickDir","down", ...
    "MajorTickLength",km2nm(25),...
    "MinorTickLength",km2nm(12.5))

Change the ruler styles.

setm(handlem("scaleruler1"),"RulerStyle","lines")
setm(handlem("scaleruler2"),"RulerStyle","patches")

Object Properties

Properties That Control Appearance

Color

ColorSpec {no default}

Color of the displayed graphic scale — Controls the color of the graphic scale lines and text. You can specify a color using a vector of RGB values or one of the MATLAB^® predefined names. By default, the graphic scale is displayed in black ([0 0 0]).

FontAngle

{normal} | italic | oblique

Angle of the graphic scale label text — Controls the appearance of the graphic scale text components. Use any MATLAB font angles.

FontName

courier | {helvetica} | symbol | times

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

FontSize

scalar in units specified in FontUnits {9}

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

FontUnits

inches | centimeters | normalized | {points} | pixels

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 sets the text characters to a font whose height is one-tenth of the axes' height. The default units, points, are equal to 1/72 of an inch.

FontWeight

light | {normal} | demi | bold

Select bold or normal font — The character weight for all displayed graphic scale labels.

Label

character vector

Label text for the graphic scale — Contains a character vector 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.”

LineWidth

scalar {0.5}

Graphic scale line width — Sets the line width of the displayed scale. The value is a scalar representing points, which is 0.5 by default.

MajorTick

vector

Graphic scale major tick locations — 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.

MajorTickLabel

Cell array of character vectors

Graphic scale major tick labels — Sets the text labels associated with the major tick locations. By default, the labels are identical to the major tick locations. You can override these by providing a cell array of character vectors. There must be as many character vectors as tick locations.

MajorTickLength

scalar

Length of the major tick lines — Controls the length of the major tick lines. The length is a distance in the units of the Units property.

MinorTick

vector

Graphic scale minor tick locations — 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.

MinorTickLabel

character vectors

Graphic scale minor tick labels — Sets the text labels associated with the minor tick locations. By default, the label is identical to the last minor tick location. You can override this by providing a character vector label.

MinorTickLength

scalar

Length of the minor tick lines — Controls the length of the minor tick lines. The length is a distance in the units of the Units property.

RulerStyle

{ruler} | lines | patches

Style of the graphic scale — Selects among three different kinds of graphic scale displays. The default ruler style looks like n axes' 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.

TickDir

{up} | down

Direction of the tick marks and text — Controls the direction in which the tick 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 the location given in the XLoc property. In the down position, the tick marks and labels are drawn below the baseline.

TickMode

{auto} | manual

Tick locations mode — Controls whether the tick locations and labels are computed automatically or are 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 to 'auto'. Setting the tick mode to 'auto' clears any explicitly specified tick locations and labels, which are then replaced by default values.

XLoc

scalar

X-location of the graphic scale — 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. You can also move the graphic scale by dragging the baseline with the mouse.

YLoc

scalar

Y-location of the graphic scale — 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. You can also move the graphic scale by dragging the baseline with the mouse.

Properties That Control Scaling

Azimuth

scalar

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.

Lat

scalar

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.

Long

scalar

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.

Radius

Name or radius of reference sphere

Reference sphere name or radius — The radius property controls the scaling between angular and surface distances. radius can be one of the character vectors supported by km2deg, or it can be the (numerical) radius of the desired sphere in the same units as the Units property. The default is 'earth'.

Units

(valid distance unit)

Surface distance units — Defines the distance units displayed in the graphic scale. Units can be any distance unit recognized by unitsratio. The distance character vector is also used in the last graphic scale text label.

Other Properties

Children

(read-only)

Name of graphic scale elements — Contains the tag assigned to the graphic elements that compose 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.

Tips

You can reposition graphic scale objects by dragging them with the mouse. You can also change their positions by modifying the XLoc and YLoc properties using setm.

Use scaleruler off, clmo scaleruler, or clmo scalerulerN to remove the scale rulers. You can also remove a graphic scale object with delete(h), or delete(handlem(`scalerulerN')), where N is the corresponding integer.

Version History

Introduced before R2006a