GridGenerator Class
Generates the grid lines for a given coordinate reference system.
NuGet/Assembly: Carmenta.Engine.5.16.2.nupkg (in the CEOperators assembly)
Syntax
public class GridGenerator : GeneratorRemarks
A GridGenerator generates a grid for a given Coordinate Reference System (CRS). The layer displaying the grid should not cache its visualizations: that is, it should not be under a TileLayer and it should not use any dynamic CacheMode.
Since the grids will be reprojected and displayed in the View.Crs, which may differ from the grid CRS, a grid can appear as curved lines. The generated grid consists of line features, normally with attributes for grid labels such as longitudes and latitudes, and also with extra attributes that can be used to improve the label placement. The lines are generated from west to east and south to north. In rare cases, you may also want to generate polygon features that are Rectangles.
To annotate the grid with the line labels, you need a TextVisualizer which takes its text from the value attribute of each line. If the other properties of the text visualizer have default values, you will get line labels at the start of each line (the west or south end).
However, a common problem with a default text visualizer is that grid line labels can appear where they should not:
 |
In this screenshot, there is a single longitude label among several latitude labels along the left edge, and a single latitude label among several longitude labels along the bottom edge. Such a mixture of latitude and longitude labels along an edge can cause confusion especially when prefixes like N and W are not used, and labels could also collide.
So, the GridGenerator generates extra line attributes that can be used in the text visualizer Condition to suppress unwanted labels. The extra attributes that are simplest to use are named impactAngleAtStart and impactAngleAtFinish, and give the angle (0° to 90°) between a map window edge and the start or the finish of the grid line. An unwanted label normally occurs when there is a small angle between the line and the map window edge. So, to omit unwanted labels at the start of the grid lines, you can add the condition
impactAngleAtStart > 45
to the text visualizer. If you instead are using a text visualizer with at = 1.0 to display the label where each line finishes (the north or east end), the condition to omit unwanted labels should be
impactAngleAtFinish > 45
These conditions usually work well also when the view has a rotation.
When a line starts or finishes in the interior of the map window, these angle attributes will get one of the special values 91° or −91°, with the negative angle indicating that the line end is a bad place for a label, according to a rule of thumb. So the conditions above should give good results in most cases also for interior line ends.
However, note that if your text visualizer has default properties, then the alignments will be TextVisualizer.AlignX = Left and TextVisualizer.AlignY = Baseline, and if the view rotation causes a grid line to start from the right edge or the top edge, then a label at the line start would be placed just outside the map window and cannot be seen. There are various ways to design the text visualizer to get visible grid line labels regardless of view rotation: see the map configuration sample grid.px for some ideas.
attribute name | possible values | meaning |
|---|---|---|
lineType | 0 and 1 | 0 means horizontal, 1 means vertical. Mnemonic: the digit 1 is a vertical line. |
value | a number or a string | The longitude or latitude, or easting or northing, of a line; controlled via the ValueAttributeFormat property. It is possible to give the attribute another name via the ValueAttribute property. |
impactAngleAtStart | a number, usually between 0° and 90° | If the line starts from an edge of the map window, this is the angle between the line start and the edge. If the line starts in the interior of the map window, the value is 91° if it makes sense to place a label there and −91° otherwise. However, if the grid generator is under a TileLayer (not recommended), the value will always be 91°. |
impactAngleAtFinish | a number, usually between 0° and 90° | If the line ends on an edge of the map window, this is the angle between the line end and the edge. If the line ends in the interior of the map window, the value is 91° if it makes sense to place a label there and −91° otherwise. However, if the grid generator is under a TileLayer (not recommended), the value will always be 91°. |
startType | an Atom: one of #left, #right, #top, #bottom and #interior. | Indicates which map window edge the line starts from, if any. Will not be defined under a TileLayer. |
finishType | an Atom: one of #left, #right, #top, #bottom and #interior. | Indicates which map window edge the line finishes at, if any. Will not be defined under a TileLayer. |
If you want to refine the conditions for label visualizers, you might also have use for the current value of View.Rotation, which is available in conditions as an update attribute named updateCameraBearing.
Inheritance Hierarchy
System.Object (not available in C#)
EngineObject
Operator
Generator
GridGenerator
Platforms
Windows, Linux, Android
GridGenerator Members
The GridGenerator type has the following members.
Constructors
| Name | Description |
|---|---|
| GridGenerator | Initializes a new instance of the GridGenerator class with the given line distances. |
Properties
| Name | Description |
|---|---|
| Bounds | Gets or sets the bounding rectangle of the grid lines. |
| Crs | Gets or sets the coordinate reference system of the grid lines. |
| Description | Gets or sets a short description of the operator. Inherited from Operator |
| DisplayName | Gets or sets a display name for the operator. Inherited from Operator |
| IsDisposed | Gets a value that tells whether the current GridGenerator has been disposed. Inherited from EngineObject |
| IsoMetadataDocument | Gets or sets the path to an ISO 19139 metadata document for the operator. Inherited from Operator |
| LineDistanceX | Gets or sets the distance between vertical grid lines. |
| LineDistanceY | Gets or sets the distance between horizontal grid lines. |
| Name | Gets or sets the name of the operator. Inherited from Operator |
| NativeHandle | Gets the native Carmenta Engine kernel object the current GridGenerator represents. Inherited from EngineObject |
| OffsetX | Gets or sets a value that offsets the grid in the x direction (east). |
| OffsetY | Gets or sets a value that offsets the grid in the y direction (north). |
| PointDistanceX | Gets or sets the distance between points in the horizontal lines. |
| PointDistanceY | Gets or sets the distance between points in the vertical lines. |
| Rectangles | Gets or sets a value that decides whether rectangular polygons between the grid lines shall be generated. |
| IUserProperties.UserProperties | Gets the AttributeSet that contains the user properties. Inherited from IUserProperties |
| ValueAttribute | Gets or sets name of the attribute that holds the labels of the grid lines. |
| ValueAttributeFormat | Gets or sets the format of the line label attribute. |
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 |
| FindChildObject | Overloaded. Finds the child object with the specified name. Inherited from Operator |
| FlushCache | Marks the layer as flushed which will release cached resources during the next update. Inherited from Operator |
| GetChildObjects | Overloaded. Gets the child objects of the current object. Inherited from Operator |
| GetFeatures | Overloaded. Gets features from the operator chain. Inherited from Operator |
| GetLocalizedDescription | Gets a localized version of the operator description in a specific language. Inherited from Operator |
| GetLocalizedDisplayName | Gets a localized version of the operator display name in a specific language. Inherited from Operator |
| GetLocalizedIsoMetadataDocument | Gets the path to an ISO 19139 metadata document for a specific language. Inherited from Operator |
| GetRasterFeature | Overloaded. Gets raster features from the operator chain and merges them into a single raster. Inherited from Operator |
| HasLocalizedDescription | Checks if a localized version of the operator description is available in a specific language. Inherited from Operator |
| HasLocalizedDisplayName | Checks if a localized version of the operator display name is available in a specific language. Inherited from Operator |
| HasLocalizedIsoMetadataDocument | Checks if an ISO 19139 metadata document is available for a specific language. Inherited from Operator |
| SetLocalizedDescription | Sets a operator description in a specific language. Inherited from Operator |
| SetLocalizedDisplayName | Sets a operator display name in a specific language. Inherited from Operator |
| SetLocalizedIsoMetadataDocument | Sets the path to an ISO 19139 metadata document for the operator, for a specific language. Inherited from Operator |