Map

Map is end of our basis tour. It forms with layers. You can simply configure the map settings and it returns a rendered map surface.

Typical map usage examples

  • Get map instance.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    function getMap() {
    const source = new ShapefileFeatureSource('./ShapeFileData.shp');
    const layer = new FeatureLayer(source);
    layer.pushStyles([new FillStyle('yellow', 'blue', 1)]);

    const map = new MapEngine(256, 256);
    map.pushLayer(layer);
    return map;
    }
  • Render it as an image

    1
    2
    3
    4
    5
    6
    7
    async function saveMapAsImageFile() {
    let map = getMap();

    const image = await map.draw();
    const imageBuffer = image.toBuffer();
    fs.writeFileSync('result.png', imageBuffer);
    }
  • Serve for tile mapping service in XYZ standard

    1
    2
    3
    4
    5
    6
    async function getTileImage(x: number, y: number, z: number) {
    let map = getMap();

    let mapImage = await map.xyz(x, y, z);
    return mapImage.toBuffer();
    }
  • Query Spatially on feature source

    1
    2
    3
    4
    5
    6
    7
    8
    async function spatialQuery(geom: Geometry) {
    let map = getMap();

    // `WGS84` is the geom CRS, used for re-projection when necessary
    // 2 is zoom level of current map state
    let features = await map.intersection(geom, 'WGS84', 2);
    return features;
    }

MapEngine Class

This class represents a complete structure of a map instance. It wraps necessary information that are used for a map rendering. A complete demo to create a map and draw as an image, then save to disk.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
export declare class MapEngine {
/**
* The name of map.
*/
name: string;
/**
* This map's spatial reference system. It applies as the target SRS to each feature source.
*/
srs: Srs;
/**
* The width of this map
*/
width: number;
/**
* The height of this map.
*/
height: number;
/**
* The background color. Default to undefined which means transparent background.
*/
background?: string;
/**
* The maximum visible scale. Defaults to positive infinity.
*/
maximumScale: number;
/**
* The minimum visible scale. Default to 0.
*/
minimumScale: number;
/**
* The layer groups that maintains the layers inside for rendering.
*/
groups: Array<LayerGroup>;
/**
* The scales list for defining the zoom levels for rendering.
*/
scales: Array<number>;
/**
* Indicates the tile origin for calculating the tile system. Default is calculating from the upper left corner.
*
* Some tiling system is calculating from lower right corner, this is the property to set.
*/
origin: TileOrigin;
renderContextOptions: RenderContextOptions;
/**
* Constructs a map engine instance.
* @param {number} width The width of map. Optional with default value 256 px.
* @param {number} height The height of map. Optional with default value 256 px.
* @param {Srs} srs The spatial reference system of this map. Optional with default value `EPSG:3857`.
* @param {Array<number>} scales The scale list that represents the zoom levels for map rendering.
*/
constructor(width?: number, height?: number, srs?: string, scales?: Array<number>);
/**
* Converts this map instance into a JSON format data.
* @returns {any} A JSON format data that is converted from this map engine.
*/
toJSON(): any;
/**
* Parses the map instance from a specified JSON format data.
* The JSON data must match the map engine schema, otherwise, it throws exception.
* @param {any} json The JSON format data that matches the map engine schema.
* @returns {MapEngine} The map engine instance that is parsed from the JSON format data.
*/
static parseJSON(json: any): MapEngine;
static fromOptions(mapOptions: MapOptions): MapEngine;
/**
* Gets the envelope of this map. It unions all the layers inside and returns a minimum envelope that includes all the visible layers.
* @returns {Envelope} The envelope of this map.
*/
envelope(): Promise<Envelope>;
/**
* This is a shortcut function for simply pushing a layer into a group. If the group doesn't exist, it automatically creates a new group to reserve the layer.
*
* @param {FeatureLayer} layer The layer to push into this map.
* @param {string} groupName The group name to reserve the layer. If there is no group matches the specific group name, a new group will be pushed into the map. Optional with default value `Default`.
*/
pushLayer(layer: FeatureLayer, groupName?: string): void;
/**
* This is a shortcut function for simply pushing layers into a group. If the group doesn't exist, it automatically creates a new group to reserve the layer.
*
* @param {Array<FeatureLayer>} layers The layers to push into this map.
* @param {string} groupName The group name to reserve the layer. If there is no group matches the specific group name, a new group will be pushed into the map. Optional with default value `Default`.
*/
pushLayers(layers: Array<FeatureLayer>, groupName?: string): void;
/**
* Pushes multiple groups into map.
* @param {...Array<LayerGroup>} groups The groups to push into this map.
*/
pushGroups(...groups: Array<LayerGroup>): void;
/**
* A shortcut function to look for a group by name.
* @param {string} name The group name.
* @returns {LayerGroup|undefined} The layer group that matches the name. If not found, returns undefined.
*/
group(name: string): LayerGroup | undefined;
/**
* A shortcut function to look for a layer by name through all groups. If the group name is defined, it only looks for the layer from the group.
* @param {string} name The layer name to look for.
* @param {string} groupName The group name where the layer is looking for.
* @returns {FeatureLayer|undefined} The layer that matches the name. If not found, returns undefined.
*/
layer(name: string, groupName?: string): FeatureLayer | undefined;
/**
* A shortcut function to look for a layer by id through all groups.
* @param {string} id The identity of a layer.
* @returns {FeatureLayer|undefined} The layer that matches the name. If not found, returns undefined.
*/
layerByID(id: string): FeatureLayer | undefined;
/**
* Query features through all feature layers with spatial relationship - intersection.
* @param geom Geometry to find intersection.
* @param geomSrs Geometry srs to find intersection.
* @param zoomLevel Zoom level number. Starts from 0.
* @param pointTolerance Tolerance for point geometry.
* @returns {Array<{layerID:string, features: Feature[]}>} The intersected features that are categorized by layers.
*/
intersection(geom: Geometry, geomSrs: string, zoomLevel: number, pointTolerance?: number, includeInvisibleLayers?: boolean, layersToQuery?: string[]): Promise<Array<{
layer: string;
features: Feature[];
}>>;
/**
* @deprecated This method is deprecated. Please call image(envelope?: IEnvelope) instead.
* @ignore
*/
draw(envelope?: IEnvelope): Promise<Image>;
/**
* Gets an image of this map instance.
* @param {IEnvelope} envelope The envelope that the viewport will be rendered. Optional with the minimal envelope of this map.
* @returns {Image} The image that is rendered with this map instance.
*/
image(envelope?: IEnvelope): Promise<Image>;
/**
* This is a shortcut function to render this map instance with XYZ tiling system.
*
* NOTE: XYZ rendering requires some other settings, it is automatically reflected to the properties on this map instance. e.g.
*
* tile width -> map.width
* tile height -> map.height
* tile zoom levels -> map.scales
* tile origin -> map.origin
* ...
*
* @param {number} x The column number. Start from 0.
* @param {number} y The row number. Start from 0.
* @param {number} z The zoom level number. Start from 0.
*/
xyz(x?: number, y?: number, z?: number): Promise<Image>;
}