Skip to content

Commit 9ac9e32

Browse files
ibgreenibgreen
committed
docs(layers): Initial TileSourceLayer docs
1 parent 8efaa04 commit 9ac9e32

File tree

1 file changed

+293
-0
lines changed

1 file changed

+293
-0
lines changed

Diff for: ‎docs/modules/layers/api-reference/tile-source-layer.md

+293
Original file line numberDiff line numberDiff line change
@@ -1 +1,294 @@
11
# TileSourceLayer
2+
3+
<p class="badges">
4+
<img src="https://img.shields.io/badge/from-v9.0-green.svg?style=flat-square" alt="from v9.0" />
5+
</p>
6+
7+
import {TileSourceLayerDemo} from '@site/src/doc-demos/geo-layers';
8+
9+
<TileSourceLayerDemo />
10+
11+
> This class is experimental, which means it does not provide the compatibility and stability that one would typically expect from other layers, detailed in the [limitations](#limitations) section. Use with caution and report any issues that you find on GitHub.
12+
13+
14+
The `TileSourceLayer` is a composite layer that connects with an image service that can render map images optimized for the current view. Instead of loading a detailed map image covering the entire globe, an image is rendered.
15+
16+
In contrast to the [TileLayer](./tile-layer.md) which loads many small image tiles, the `TileSourceLayer` loads a single image that covers the entire viewport in one single request, and updates the image by performing additional requests when the viewport changes.
17+
18+
To use this layer, an *image source* must be specified. Image sources are specified by supplying a URL to the `TileSourceLayer` `data` property. See the section on image sources below for mor information.
19+
20+
21+
import Tabs from '@theme/Tabs';
22+
import TabItem from '@theme/TabItem';
23+
24+
<Tabs groupId="language">
25+
<TabItem value="js" label="JavaScript">
26+
27+
```js
28+
import {Deck} from '@deck.gl/core';
29+
import {TileSourceLayer} from '@deck.gl/geo-layers';
30+
import {WMSSource} from '@loaders.gl/wms';
31+
32+
const wmsSource = new WMSSource({
33+
data: 'https://ows.terrestris.de/osm/service',
34+
serviceType: 'wms',
35+
layers: ['OSM-WMS']
36+
});
37+
38+
new Deck({
39+
layers: [
40+
new TileSourceLayer({source: wmsSource})
41+
],
42+
initialViewState: {
43+
longitude: -122.4,
44+
latitude: 37.74,
45+
zoom: 9
46+
},
47+
controller: true,
48+
});
49+
```
50+
51+
</TabItem>
52+
<TabItem value="ts" label="TypeScript">
53+
54+
```ts
55+
import {Deck} from '@deck.gl/core';
56+
import {TileSourceLayer} from '@deck.gl/geo-layers';
57+
58+
const layer = new TileSourceLayer({
59+
data: 'https://ows.terrestris.de/osm/service',
60+
serviceType: 'wms',
61+
layers: ['OSM-WMS']
62+
});
63+
64+
new Deck({
65+
initialViewState: {
66+
longitude: -122.4,
67+
latitude: 37.74,
68+
zoom: 9
69+
},
70+
controller: true,
71+
layers: [layer]
72+
});
73+
```
74+
75+
</TabItem>
76+
<TabItem value="react" label="React">
77+
78+
```tsx
79+
import React from 'react';
80+
import DeckGL from '@deck.gl/react';
81+
import {TileSourceLayer} from '@deck.gl/geo-layers';
82+
83+
function App() {
84+
const layer = new TileSourceLayer({
85+
data: 'https://ows.terrestris.de/osm/service',
86+
serviceType: 'wms',
87+
layers: ['OSM-WMS']
88+
});
89+
90+
return <DeckGL
91+
initialViewState={{
92+
longitude: -122.4,
93+
latitude: 37.74,
94+
zoom: 9
95+
}}
96+
controller
97+
layers={[layer]}
98+
/>;
99+
}
100+
```
101+
102+
</TabItem>
103+
</Tabs>
104+
105+
106+
## Installation
107+
108+
To install the dependencies from NPM:
109+
110+
```bash
111+
npm install deck.gl
112+
# or
113+
npm install @deck.gl/core @deck.gl/layers @deck.gl/geo-layers
114+
```
115+
116+
```ts
117+
import {TileSourceLayer} from '@deck.gl/geo-layers';
118+
import type {TileSourceLayerProps} from '@deck.gl/geo-layers';
119+
120+
new TileSourceLayer(...props: TileSourceLayerProps[]);
121+
```
122+
123+
To use pre-bundled scripts:
124+
125+
```html
126+
<script src="https://unpkg.com/deck.gl@^9.0.0/dist.min.js"></script>
127+
<!-- or -->
128+
<script src="https://unpkg.com/@deck.gl/core@^9.0.0/dist.min.js"></script>
129+
<script src="https://unpkg.com/@deck.gl/layers@^9.0.0/dist.min.js"></script>
130+
<script src="https://unpkg.com/@deck.gl-community/layers@^9.0.0/dist.min.js"></script>
131+
```
132+
133+
```js
134+
new deck.TileSourceLayer({});
135+
```
136+
137+
## Sources
138+
139+
The `TileSourceLayer` accepts a `TileSource` and loads and renders tiles from that TileSource to cover the current viewport.
140+
141+
`loaders.gl` provides a variety of `TileSource` classes for various protocols and tile services. Generally thes sources can be created with a URL from which it can start loading map images.
142+
143+
144+
However, it is also possible to connect the TileSourceLayer to any other REST based service that can render map images from a set of web mercator bounds and a given pixel resolution (perhaps an ArcGIS image server) by specify a custom URL template.
145+
146+
### Roadmap
147+
148+
A `WMSSource` knows how to build URLs for geospatial image services such as WMS.
149+
150+
Note that additional features, such as metadata loading, is only supported for known services.
151+
152+
### Layers
153+
154+
Image servers such as WMS can render different layers. Typically as list of layers **must** be specified, otherwise requests for map images will fail. For WMS services, this is controlled by [layers](#layers). For other services, layers (if required by that service) can be specified in the template URL, either as a parameter or as a hard-coded part of the template string.
155+
156+
### Image Service Metadata
157+
158+
Image services like WMS can often provide metadata (aka capabilities) about the service, listing;
159+
- attribution information,
160+
- available layers
161+
- additional capabilities (pixel/neighborhood queries, legend generation etc).
162+
163+
The `TileSourceLayer` will automatically attempt to query metadata for known service types (currently WMS).
164+
165+
Template URLs only cover image requests and there is no support for providing a custom URL for the metadata queries. This needs to be handled by the application for non-WMS services.
166+
167+
### Interactivity
168+
169+
WMS services sometimes provide a mechanism to query a specific pixel. This is supported through the `getFeatureInfoText()` method on the `TileSourceLayer`
170+
171+
## Methods
172+
173+
#### `getFeatureInfoText` {#getfeatureinfotext}
174+
175+
This is a method on the layer that can be called to retrieve additional information from the image service about the map near the specified pixel.
176+
177+
Arguments:
178+
179+
- `x` (number) - The x component of the pixel in the image
180+
- `y` (number) - The y component of the pixel in the image
181+
182+
Returns
183+
184+
- `Promise<string>` - Resolves to a string containing additional information about the map around the provided pixel
185+
186+
187+
## Properties
188+
189+
Inherits all properties from [base `Layer`](../core/layer.md).
190+
191+
### Data Options
192+
193+
#### `data` (string) {#data}
194+
195+
A base URL to a well-known service type, or a full URL template from which the map images should be loaded.
196+
197+
If [serviceType](#servicetype) is set to `'template'`, data is expected to be a URL template. The template may contain the following substrings, which will be replaced with a viewport's actual bounds and size at request time:
198+
199+
- `{east}`
200+
- `{north}`
201+
- `{west}`
202+
- `{south}`
203+
- `{width}`
204+
- `{height}`
205+
- `{layers}` - replaced with a string built from the content of [layers](#layers). The array of layer name strings will be joined by commas (`,`) into a single string.
206+
207+
208+
#### `serviceType` (string, optional) {#servicetype}
209+
210+
- Default: `'auto'`
211+
212+
Specifies the type of service at the URL supplied in `data`. Currently accepts either `'wms'` or `'template'`. The default `'auto'` setting will try to autodetect service from the URL.
213+
214+
#### `layers` (string\[\], optional) {#layers}
215+
216+
- Default: `[]`
217+
218+
Specifies names of layers that should be visualized from the image service.
219+
220+
> Note that WMS services will typically not display anything unless at least one valid layer name is provided.
221+
222+
#### `srs` (string, optional) {#srs}
223+
224+
- Default: `'auto'`
225+
226+
Spatial Reference System for map output, used to query image from the server. Can be one of `EPSG:4326'`, `'EPSG:3857'` or `'auto'`.
227+
228+
If `'auto'`, the layer will request `EPSG:3857` in `MapView`, and `EPSG:4326` otherwise. Note that a particular SRS may not be supported by your image server.
229+
230+
231+
### Callbacks
232+
233+
#### `onMetadataLoad` (Function, optional) {#onmetadataload}
234+
235+
`onMetadataLoad` called when the metadata of the image source successfully loads.
236+
237+
- Default: `metadata => {}`
238+
239+
Receives arguments:
240+
241+
- `metadata` (object) - The metadata for the image services has been loaded.
242+
243+
Note that metadata will not be loaded when [serviceType](#servicetype) is set to `'template`.
244+
245+
#### `onMetadataLoadError` (Function, optional) {#onmetadataloaderror}
246+
247+
`onMetadataLoadError` called when metadata failed to load.
248+
249+
- Default: `console.error`
250+
251+
Receives arguments:
252+
253+
- `error` (`Error`)
254+
255+
#### `onImageLoadStart` (Function, optional) {#onimageloadstart}
256+
257+
`onImageLoadStart` is a function that is called when the `TileSourceLayer` starts loading metadata after a new image source has been specified.
258+
259+
- Default: `data => null`
260+
261+
Receives arguments:
262+
263+
- `requestId` (`number`) - Allows tracking of specific requests
264+
265+
#### `onImageLoad` (Function, optional) {#onimageload}
266+
267+
`onImageLoad` called when an image successfully loads.
268+
269+
- Default: `() => {}`
270+
271+
Receives arguments:
272+
273+
- `requestId` (`number`) - Allows tracking of specific requests
274+
275+
#### `onImageLoadError` (Function, optional) {#onimageloaderror}
276+
277+
`onImageLoadError` called when an image failed to load.
278+
279+
- Default: `console.error`
280+
281+
Receives arguments:
282+
283+
- `requestId` (`number`) - Allows tracking of specific requests
284+
- `error` (`Error`)
285+
286+
## Limitations
287+
288+
- Each instance of the `TileSourceLayer` only supports being rendered in one view. See [rendering layers in multiple views](../../developer-guide/views.md#rendering-layers-in-multiple-views) for a workaround.
289+
- This layer currently does not work well with perspective views (i.e. `pitch>0`).
290+
- This layer does not work with non-geospatial views such as the [OrthographicView](../core/orthographic-view.md) or the [OrbitView](../core/orbit-view.md).
291+
292+
## Source
293+
294+
[modules/geo-layers/src/wms-layer](https://github.com/visgl/deck.gl/tree/master/modules/geo-layers/src/wms-layer)

0 commit comments

Comments
 (0)