ScaleBar Class
A ScreenElement that contains a scale bar and can be displayed by a ScreenLayer.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class ScaleBar : ScreenElementRemarks
A scale bar indicates the map scale in an intuitive way, as a line or bar whose length is given by a label. A scale bar can also be called a bar scale, linear scale, graphic scale or graphical scale. Compared to a representative fraction like 1 : 5000, a scale bar has the advantage that it will remain valid even if the map is resized outside your GIS system: for example, if someone takes a map window screenshot and resizes it to send it to a printer, or to insert it in a document.
 |
In Carmenta Engine, a ScaleBar can be used as an element of a ScreenLayer, which will place it in a corner of the map window, or at a constant offset from the corner. Such a scale bar will be dynamic in that it will update itself when you zoom in or out. In fact, it will also update itself when you are panning, because the ScaleBar is based on the local map scale in the center of the View area, while it is the nominal scale that is kept constant during panning (at least when you pan with the StandardTool). See scale, map to learn more about local and nominal scale.
A scale bar is most accurate when the View.Crs is based on a conformal map projection and the View is zoomed in to a detailed scale. For more details see the section below, When not to display a scale bar.
A ScaleBar cannot be used in a GlobeView, only in a 2D map.
Overview of Properties
The ScaleBar appearance cannot be controlled via user-defined visualizers, but you can choose a basic Style as one of Comb, DoubleSidedComb, Boxes or DoubleBoxes as shown in the screenshot above; see also ScaleBarStyle. You can control the Font, the HaloWidth and the LineWidth, as well as a number of colors:
BackgroundColor. The color of the background rectangle.
Color. The color of the labels and the lines.
HaloColor. The color of the halo for labels and for lines.
FillColor1. The first fill color for boxes.
FillColor2. The second fill color for boxes.
OutlineColor. The color of the background rectangle outline.
To control the size of the ScaleBar element, you can adjust the Height, the MaxLengthPixels and the size of the Font, as well as the basic ScreenElement properties OutlineMargin and OutlineWidth. You can also control the number of Divisions of the scale bar, although you cannot specify an integer, just an enumeration value that can be One, Few or Several.
When a scale bar has only one division, there will be only one numeric label since the zero label will not be shown (see screenshot above), and you can use the NumberPlacement property to place the single numeric label above or below the scale bar graphic, or to its left or right. When there is more than one division, there will be several numeric labels and they must be placed either above or below the scale bar. The similar UnitPlacement property lets you place the unit label above, below, or left or right of the scale bar regardless of the number of divisions; you can also place it directly after the last number label.
As for the length unit, you often want the scale bar to use different units depending on map scale, for example either meters or kilometers. So, the ScaleBar class has two length unit properties, the ShortUnit to be used when zoomed in, and the LongUnit to be used when zoomed out. The switch between them happens automatically and depends only on the MaxLengthPixels and the current map scale: the long unit will be used unless that would make the scale bar shorter than one long unit. If you want the same unit in all scales, for example the nautical mile, you must set the nautical mile as both the short and the long unit. See also the section below, Automatic switching between more than two units.
The unit label to display will be the LengthUnit.Abbreviation, unless you override it by setting the ShortUnitLabel and the LongUnitLabel.
Note that the LengthUnit class allows the definition of arbitrary units. For example, you can define a kiloyard that is 914.4 meters long and abbreviated as "kyd". (The kiloyard is not common enough to be predefined, but it is used in US submarine operations.)
Advanced Use
For most purposes, is should be enough to use the ScaleBar properties in a straightforward way, but this section describes some further possibilites that may be less obvious.
Fine-tuning the visualization
If you want to fine-tune the visualization, there are four properties that can be attribute variables that depend on feature attributes:
Font. The font for the number labels and the unit label.
Color. The color of labels and lines.
HaloColor. The color of the halo for labels and lines.
HaloWidth. The width of the halo for labels and lines.
The scale bar graphic consists of line features and possibly polygon features for boxes, while the labels are generated from point features. These features have two available attributes, geoType and scaleBarPartType, whose values will be atoms.
The value of the geoType attribute will be #point, #line or #polygon, as usual.
The value of the scaleBarPartType attribute will be #line, #number or #unit. If the unit label is placed directly after the last number label, they will be combined and attached to a single point feature, whose value of scaleBarPartType will be #number. The box polygons will not get any scaleBarPartType attribute, because there is no attribute variable that can affect them anyway.
Note that the ScaleBar properties that are attribute variables cannot depend on any of the View.UpdateAttributes.
Let us say you want to display a scale bar where the unit font is larger than the number font. This would be impossible if the unit label is placed directly after the last number label, since they will then be rendered as a single combined label. But it is possible if you let the NumberPlacement be Above and the UnitPlacement be Below, for example. The default font of Carmenta Engine is Arial 14pt, so you can construct a larger font that can be called Arial_20_normal_normal. You can then define the Font property like this, using the scaleBarPartType:
 |
which can give a scale bar like this:
 |
If you want to display the two types of labels in the same way, but you need an attribute variable that gives different values for the scale bar graphic and for the labels, you can use the geoType instead of the scaleBarPartType. For example, if you want black scale bar lines but blue labels, you can define the Color property like this in Carmenta Studio:
 |
which can give a scale bar like this:
 |
This example just showed the technique – the black-and-blue color scheme does not make much sense. But if you feel creative, you can design hybrid styles by placing two ScaleBar instances with different styles in the same position, and then one of them will need invisible labels while the other may need an invisible graphic:
 |
Using nautical miles
To display a scale bar with nautical miles, you probably want to use the nautical mile both as the ShortUnit and as the LongUnit, since there is no shorter unit associated with it. So when you zoom in far, a scale bar in nautical miles must display tiny numbers like 0.05, which can be impractical. One solution can be to display an additional scale bar using meters and kilometers, and just turn off the nautical scale bar when zoomed in enough – you can do that by placing the nautical scale bar in its own ScreenLayer where you set Layer.MinScale to be 10 000, say.
Automatic switching between more than two units
Based on the map scale, a ScaleBar instance will automatically switch between its two units, LongUnit and ShortUnit, for example between miles and feet, which should be enough for many applications. But if your application can be very zoomed in, you may want to display a scale bar that automatically switches between three units, for example miles, feet and inches. Then you can use two ScaleBar instances, each in its own ScreenLayer: the first ScaleBar uses miles and feet while the second uses feet and inches. And you should select a threshold scale at about 1 : 500 which you use both as the Layer.MinScale for the miles/feet scale bar and as the Layer.MaxScale for the feet/inches scale bar, to ensure that exactly one of the two ScaleBar instances will be displayed. The suitable threshold scale depends on the MaxLengthPixels, but there will be a fairly wide range of scales where both scale bars would use feet, so there will be a wide range of threshold values that will work.
In the UK, the yard is more common than in the US, so for British users you may want to display a scale bar that switches automatically between four units: miles, yards, feet and inches. This can also be done with two ScaleBar instances: the one for zoomed-out scales should use miles and yards, and the one for zoomed-in scales should use feet and inches. In this case, you must be more careful when choosing the threshold scale, to make the switch between yards and feet happen where it looks natural, and you may need to recalibrate the threshold scale if you decide to change the MaxLengthPixels. An example can be found in the sample configuration screen_elements.px.
Using two ScaleBar instances to get more than two units is a bit cumbersome, so the common case of a metric ScaleBar instance is handled in a special way and will normally give you four units. That is, if the ShortUnit is the meter and the LongUnit is longer, you will get an automatic switch to centimeters or millimeters when zooming in enough. We think this is what most users want, and in any case it is easy to convert centimeters to meters in your head. However, the unit labels for the automatic centimeters and millimeters will always be "cm" and "mm", so if you want a "Centimeters" label, you must instead use the general idea with two ScaleBar instances and a threshold scale.
There is no specific ScaleBar property that will disable the automatic centimeters and millimeters, but if you need to do that, you have a few options. The simplest option is to use the meter (or the kilometer) as both the LongUnit and the ShortUnit, which will cause the repeated unit to be used in all scales. But suppose you do want the automatic switch between kilometers and meters, just not the centimeters or millimeters. In that case, you can again use two ScaleBar instances and a threshold scale: the ScaleBar for zoomed-out scales should use kilometers and meters, while the one for zoomed-in scales should use the meter for both the long and the short unit. Alternatively, you can use a single ScaleBar instance and a trick: the LongUnit should be the kilometer but the ShortUnit should differ very slightly from a meter. For example, you can define a LengthUnit representing the German legal meter used in Namibia (EPSG code 9031), which equals 1.0000135965 standard meters. Such a unit will disable the automatic centimeters and millimeters, since they can appear only when the short unit is exactly one meter.
When not to Display a Scale Bar
Since the Earth is round and a 2D map is not, a 2D map cannot have a constant scale everywhere: only a globe can have that. The scale variation depends on both the map projection and on how much of the Earth that is displayed: the variation is negligible in a city map but large in a hemisphere map or a world map. That is: when you zoom out, the scale variation will increase, which makes a scale bar less useful and potentially misleading, so a ScreenLayer displaying a scale bar should have a defined value for Layer.MaxScale that will disable the layer when it has been zoomed out too far. But it is hard to recommend any specific value for the MaxScale, since it depends on your needs.
According to some nautical handbooks, a printed nautical chart in the Mercator projection should have a scale bar only if the map scale is more detailed than about 1 : 80 000. But even if you aim for the same accuracy, you should be able to set a more permissive MaxScale value, since your map window will usually be much smaller than a printed chart, and since the Layer.MaxScale will be compared to the nominal scale of the View, not the actual local map scale (see scale, map). So, setting the MaxScale to something like 500 000 should agree with the spirit of the nautical handbooks. And if the View does not use Mercator but a map projection adapted to an area of interest far from the equator, then it makes sense to display a scale bar in more zoomed-out scales than you would allow in Mercator, since the scale variation across the area of interest will be smaller. And there are also public web maps in Mercator where a scale bar is displayed in all scales. So we can just say that the MaxScale value should be somewhere between half a million and infinity...
In map scales where a scale bar would be too misleading for your purposes, you can indicate distances on the map in other ways: you can use a RangeOperator, or you can design an interactive tool for measuring distances between clicked screen points. You can also display a UTM grid, since the fine grid of UTM is based on projected meters whose scale distortions are small thanks to the narrow UTM zones. Or you can simply display a LongLat graticule, if your GIS system users know that one arc minute of latitude is about one nautical mile and that one degree of latitude is about 111 km.
A scale bar in Carmenta Engine is always based on the local scale at the center of the View.Area. In the general case, the local scale at the center may be different in the x and y directions, and then the average of them will be used, but that is unusual: most map projections used in GIS systems are conformal, which means that the local scale at a point will be the same in all directions. If you do want to use a scale bar in a View with a non-conformal map projection, it is wise to add some View.Constraints that ensure that the View center is always in the reasonably good area of the map projection, otherwise the scale bar can be misleading even when the View is zoomed in.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
ScreenElement
ScaleBar
Platforms
Windows, Linux, Android
See Also
Reference
Core Module
ScaleBarDivisions
ScaleBarNumberPlacement
ScaleBarStyle
ScaleBarUnitPlacement
ScreenLayer.Elements
ScaleBar Members
The ScaleBar type has the following members.
Constructors
| Name | Description |
|---|---|
| ScaleBar | Initializes a new instance of the ScaleBar class. |
Properties
| Name | Description |
|---|---|
| AlignLeft | Gets or sets a flag that controls horizontal alignment of the entire element. Inherited from ScreenElement |
| AlignTop | Gets or sets a flag that controls vertical alignment of the entire element. Inherited from ScreenElement |
| BackgroundColor | Gets or sets the background color. Inherited from ScreenElement |
| Color | Gets or sets the color for labels and for the lines of the graphic. |
| Divisions | Gets or sets an enumeration value that controls the number of divisions. |
| FillColor1 | Gets or sets the first fill color for boxes. |
| FillColor2 | Gets or sets the second fill color for boxes. |
| Font | Gets or sets the font for labels. |
| HaloColor | Gets or sets the halo color for labels and for the lines of the graphic. |
| HaloWidth | Gets or sets the halo width for labels and for the lines of the graphic. |
| Height | Gets or sets the height of the scale bar graphic in pixels, excluding labels and background. |
| IsDisposed | Gets a value that tells whether the current ScaleBar has been disposed. Inherited from EngineObject |
| LineWidth | Gets or sets the width of the lines in the scale bar graphic. |
| LongUnit | Gets or sets a long length unit, used when zoomed out. |
| LongUnitLabel | Gets or sets an explicit label for the long unit. |
| MaxLengthPixels | Gets or sets the maximal length of the scale bar graphic, in pixels, excluding labels and background. |
| Name | Gets or sets the name of the ScaleBar. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current ScaleBar represents. Inherited from EngineObject |
| NumberPlacement | Gets or sets an enumeration value that controls where the number labels are placed. |
| OffsetX | Gets or sets a rightward pixel offset for the element (rightward is the screen x axis direction). Inherited from ScreenElement |
| OffsetY | Gets or sets a downward pixel offset for the element (downward is the screen y axis direction). Inherited from ScreenElement |
| OutlineColor | Gets or sets the color of the screen element outline. Inherited from ScreenElement |
| OutlineMargin | Gets or sets the distance between the screen element outline and its contents. Inherited from ScreenElement |
| OutlineWidth | Gets or sets the width of the screen element outline. Inherited from ScreenElement |
| ShortUnit | Gets or sets a short length unit, used when zoomed in. |
| ShortUnitLabel | Gets or sets an explicit label for the short unit. |
| Style | Gets or sets an enumeration value that controls the visual style of the scale bar. |
| UnitPlacement | Gets or sets an enumeration value that controls where the unit label is placed. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
Methods
| Name | Description |
|---|---|
| Clone | Creates a copy of an object. Inherited from EngineObject |
| Dispose | Releases the reference to the native Carmenta Engine kernel instance the EngineObject represents. Inherited from EngineObject |
| Equals | Determines whether this instance is equal to another. Inherited from EngineObject |