NorthArrow Class
A ScreenElement that contains a north arrow symbol and can be displayed by a ScreenLayer.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CECore assembly)
Syntax
public class NorthArrow : ScreenElementRemarks
A NorthArrow screen element displays a dynamic north arrow symbol in a corner of the map window, or at a constant offset from a corner. The Symbol will indicate the true north direction at the center of a 2D View.Area or at a 3D camera position, and must be an SvgSymbol, a RasterSymbol or a CustomSymbolProxy. There are two predefined symbols that are suitable, Symbol.NorthArrow and Symbol.NorthArrowN, and you can modify their size and colors via properties of the NorthArrow class. You can also design your own symbol, for example a compass rose.
 |
 |
 |
In a 3D presentation, the north arrow will still be a 2D symbol. You can regard it as being painted on a billboard facing the camera, and to see the north direction in the 3D perspective, you must imagine pushing the billboard over until it becomes horizontal. More technically, the 2D symbol is rotated counter-clockwise from screen up by the same angle that the camera bearing has been rotated clockwise from north. In the screenshot, the camera bearing is 19° clockwise from north, as you can see in the status bar, so the north arrow is rotated 19° counterclockwise from screen up.
There are two reasons why true north may differ from screen up:
A 2D map can have a non-zero View.Rotation, for example if the map window shows a moving map that is centered on a moving aircraft and oriented with heading up. Similarly, a 3D presentation could have a non-zero GlobeView.CameraBearing; in other words, the camera need not look northward.
In a 2D map, even if the View.Rotation is zero, that means only that screen up indicates grid north, which is the northish direction according to the projected grid of the View.Crs, and which can differ from true north. In the Lambert Conformal Conic projection, for example, true north will differ from grid north except along a central meridian. This is the case in the Iceland map above, where the map projection of the pan-European Crs.EtrsLcc is conic with only the meridian at 10°E appearing vertical.
The size of the background rectangle will be based on the symbol size and on the OutlineMargin, but the rectangle size will not change dynamically to fit snugly around the current rotation of the symbol. Instead, the background rectangle will always be a static square that should be large enough for any rotation of the symbol. The size of a user-defined symbol may be overestimated, but you can compensate by decreasing the OutlineMargin; the sample configuration screen_elements.px gives an example with a negative value.
When not to display a NorthArrow element
If a 2D map uses the Mercator projection, displaying a north arrow or a compass rose is completely safe (but usually unnecessary if the View.Rotation is zero). However, if the map uses a projection that is not cylindrical, the true north direction will vary across the map window, and the variation will be small or negligible only if the View is zoomed in enough. So in that case, you should set a Layer.MaxScale on the ScreenLayer that displays the NorthArrow element. Regardless of the max scale, the NorthArrow element will disable itself automatically in a 2D map whenever the north pole or the south pole is visible as a single point in the View area, because then there will be visible positions where the north direction differs 180° from the central one.
In polar areas or in zoomed-out scales where you want the north arrow turned off, you can indicate north by displaying a LongLat graticule, or you can use a RangeOperator with a RangeOperator.RadialCount of 8, say.
Even if you set a Layer.MaxScale, a north arrow symbol or a compass rose can be misleading if the map projection for a 2D map is not conformal; in other words, if it does not preserve angles. This is seldom a problem since most map projections used for GIS and for detailed printed maps are conformal, so when you know the north direction, you also know that east is 90° clockwise from north, etc. But if you do use a non-conformal map projection and display a compass rose symbol in your NorthArrow element, the N spike will point to true north, but the E spike may not point to true east. Or even if both the N and the E spikes are pointing correctly, the NE spike may not: the Miller Cylindrical and LongLat are examples of that.
 |
Above, a point on Jan Mayen is used as input to a RangeOperator which gives correct circles and radials, but in the compass rose only the four main spikes point in the right directions, since the symbol ignores the shearing caused by using LongLat as a map projection.
And map projections that are equal-area cannot be conformal, although they are approximately conformal in their intended area of use. Our next example uses a Lambert Azimuthal Equal Area projection too far from its center:
 |
Here, only the N and S spikes of the compass rose are pointing in the right directions. To make all spikes correct, the compass rose would need to be sheared in the same way as the Equador map, but the NorthArrow element does not support shearing the symbol. If the symbol had been a single-spike north arrow instead, one could argue that it would be correct in a literal sense, but when map users see a north arrow, they will assume that east is 90° from north, etc., so it would still be misleading.
To conclude: if the map projection is non-conformal, a north arrow or a compass rose can be misleading even if the View is zoomed in, so using a Layer.MaxScale does not help in this case. As a simple extra safeguard, you can define View.Constraints to ensure that the View center will always stay inside the good area of the projection. For the CRS used above, the ETRS89 / LAEA Europe which is centered in Germany, the angle distortion is less than 2° within the continental EU and less than 4° on Svalbard, but up to 40° in Equador.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
ResourceObject
ScreenElement
NorthArrow
Platforms
Windows, Linux, Android
NorthArrow Members
The NorthArrow type has the following members.
Constructors
| Name | Description |
|---|---|
| NorthArrow | Initializes a new instance of the NorthArrow 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 main color for the symbol. |
| FillColor1 | Gets or sets the first fill color for the symbol. |
| FillColor2 | Gets or sets the second fill color for the symbol. |
| HaloColor | Gets or sets the halo color for the symbol. |
| IsDisposed | Gets a value that tells whether the current NorthArrow has been disposed. Inherited from EngineObject |
| Name | Gets or sets the name of the NorthArrow. Inherited from ResourceObject |
| NativeHandle | Gets the native Carmenta Engine kernel object the current NorthArrow represents. Inherited from EngineObject |
| 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 |
| Symbol | Gets or sets the north arrow symbol. |
| SymbolScale | Gets or sets a scale factor by which the symbol will be enlarged. |
| 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 |