Skip to content

Commit b85ab97

Browse files
m-mohrm-mohr
committed
Improvements for the actions, including better action documentation radiantearth#354, removed GeoParquet action for now
1 parent 295a648 commit b85ab97

File tree

6 files changed

+131
-150
lines changed

6 files changed

+131
-150
lines changed

‎assetActions.config.js‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ import CopcViewer from './src/actions/assets/CopcViewer.js';
44
import F3D from './src/actions/assets/F3D.js';
55
import GeoJsonIo from './src/actions/assets/GeoJsonIo.js';
66
// import Geofox from './src/actions/assets/Geofox.js';
7-
// import Geoparquet from './src/actions/assets/Geoparquet.js';
87
// import Potree from './src/actions/assets/Potree.js';
98
import Protomaps from './src/actions/assets/Protomaps.js';
109

@@ -14,7 +13,6 @@ export default {
1413
CopcViewer,
1514
F3D,
1615
GeoJsonIo,
17-
// Geoparquet, // not ready yet
1816
// Potree,
1917
Protomaps,
20-
};
18+
};

‎docs/actions.md‎

Lines changed: 79 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,124 @@
1-
# Actions
1+
# Actions <!-- omit in toc -->
22

33
STAC Browser has a pluggable interface to share or open assets and links with other services, which we call "actions".
44

55
An action adds a button to an asset or link if certain requirements are met, which can then be executed by users.
66
For example, you could open COPC files in a dedicated COPC Viewer, which otherwise you could only download.
77

8-
## Assets
8+
- [User Guide](#user-guide)
9+
- [Assets](#assets)
10+
- [Links](#links)
11+
- [Developer Guide](#developer-guide)
912

10-
All actions for assets are stored in the folder [`src/actions/assets`](../src/actions/assets).
11-
They all implement the [`AssetActionPlugin` interface](../src/actions/AssetActionPlugin.js).
12-
The actions can be enabled by adding them to the [`assetActions.config.js`](../assetActions.config.js) file.
13+
## User Guide
1314

14-
### copc.io
15+
### Assets
1516

16-
Adds an `Open in copc.io` button that allows to open Cloud-Optimized Point Cloud (COPC) files on <https://viewer.copc.io>.
17+
The following actions are available:
1718

18-
```js
19-
import CopcViewer from './src/actions/assets/CopcViewer.js';
20-
export default { CopcViewer };
21-
```
19+
- `Cesium`: Allows to open OGC 3D Tiles (media type `application/3dtiles+json`) files through the Cesium Sandcastle at <https://sandcastle.cesium.com>.
20+
- `CopcViewer`: Allows to open Cloud-Optimized Point Cloud (COPC, media type `application/vnd.laszip+copc`) files through the Hobu COPC Viewer at <https://viewer.copc.io>.
21+
- `F3D`: Allows to open 3D models (media types `model/gltf-binary`, `model/gltf+json`, and `application/fbx`) files through the F3D Web App at <https://f3d.app/web>.
22+
- `Felt`: Allows to open GeoTIFF, GeoJON and KML/KMZ files through Felt at <https://felt.com/map/>.
23+
- `Geofox`: Allows to open OGC 3D Tiles (media type `application/3dtiles+json`) files through the 3D Assets Viewer at <https://viewer.geofox.ai>.
24+
- `GeoJsonIo`: Allows to open GeoJON files through [geojson.io](https://geojson.io).
25+
- `Potree`: Allows to open Cloud-Optimized Point Cloud (COPC, media type `application/vnd.laszip+copc`) and Potree files (file names `cloud.js`, `metadata.json`, `ept.json`) files through the Potree Viewer at <https://3d.iconem.com/apps/load_potree_project_from_urlparam/>.
26+
- `Protomaps`: Allows to open PMTiles (media type `application/vnd.pmtiles`) files through PMTiles Viewer at <https://pmtiles.io>.
2227

23-
### Felt (Assets)
28+
All actions for assets are stored in the folder [`src/actions/assets`](../src/actions/assets) if you want to inspect them.
2429

25-
Adds an `Open in Felt` button that allows to import KML, KMZ, GeoTiff and GeoJSON assets to <https://felt.com>.
30+
The actions can be enabled by adding them to the [`assetActions.config.js`](../assetActions.config.js) file.
31+
Open the file and you'll see a number of imports and exports.
32+
Import the file for the action that you want to enable, e.g. for Felt:
2633

2734
```js
2835
import Felt from './src/actions/assets/Felt.js';
29-
export default { Felt };
3036
```
3137

32-
### geojson.io
38+
The path is fixed to `./src/actions/assets/`, the file extension is always `.js`.
39+
In-between add the file name from the list above.
40+
The import name should be the file name without extension (i.e. `Felt` again).
3341

34-
Adds an `Open in geojson.io` button that allows to open GeoJSON files on <https://geojson.io>.
42+
Lastly, add the import name to the list of exports, e.g.
3543

3644
```js
37-
import GeoJsonIo from './src/actions/assets/GeoJsonIo.js';
38-
export default { GeoJsonIo };
45+
export default {
46+
OtherAction,
47+
Felt
48+
};
3949
```
4050

41-
### OGC3dTiles
51+
Save the file and restart / rebuild STAC Browser.
4252

43-
Adds an `Open in Geofox.ai` button that allows to open OGC 3D Tiles files on <https://viewer.geofox.ai> or Cesium Sandcastle.
53+
### Links
4454

45-
```js
46-
import OGC3dTiles from './src/actions/assets/OGC3dTiles.js';
47-
export default { OGC3dTiles };
48-
```
55+
The following actions are available:
4956

50-
### geoparquet.info
57+
- `Cesium`: Allows to open OGC 3D Tiles (relation type `3d-tiles`, see [web-map-links extension](https://github.com/stac-extensions/web-map-links/blob/v1.2.0/README.md#3d-tiles)) files through the Cesium Sandcastle at <https://sandcastle.cesium.com>.
58+
- `Felt`: Allows to open XYZ tile services (relation type `xyz`, see [web-map-links extension](https://github.com/stac-extensions/web-map-links/blob/v1.2.0/README.md#xyz)) files through Felt at <https://felt.com/map/>.
59+
- `Geofox`: Allows to open OGC 3D Tiles (relation type `3d-tiles`, see [web-map-links extension](https://github.com/stac-extensions/web-map-links/blob/v1.2.0/README.md#3d-tiles)) files through the 3D Assets Viewer at <https://viewer.geofox.ai>.
60+
- `Protomaps`: Allows to open PMTiles (relation type `pmtiles`, see [web-map-links extension](https://github.com/stac-extensions/web-map-links/blob/v1.2.0/README.md#pmtiles)) files through PMTiles Viewer at <https://pmtiles.io>.
5161

52-
Adds an `Open in geoparquet.info` button that allows to open GeoParquet files on <https://geoparquet.info>.
62+
All actions for assets are stored in the folder [`src/actions/links`](../src/actions/links) if you want to inspect them.
5363

54-
```js
55-
import Geoparquet from './src/actions/assets/Geoparquet.js';
56-
export default { Geoparquet };
57-
```
58-
59-
### potree.org
60-
61-
Adds an `Open in potree.org` button that allows to open COPC and Potree files on <https://potree.org> (via [Darren Wiens](https://mpc-copc-viewer.netlify.app) or [Iconem](https://3d.iconem.com/apps/load_potree_project_from_urlparam) apps)
64+
The actions can be enabled by adding them to the [`linkActions.config.js`](../linkActions.config.js) file.
65+
Open the file and you'll see a number of imports and exports.
66+
Import the file for the action that you want to enable, e.g. for PMTiles / Protomaps:
6267

6368
```js
64-
import Potree from './src/actions/assets/Potree.js';
65-
export default { Potree };
69+
import Protomaps from './src/actions/links/Protomaps.js';
6670
```
6771

68-
### pmtiles.io
72+
The path is fixed to `./src/actions/links/`, the file extension is always `.js`.
73+
In-between add the file name from the list above.
74+
The import name should be the file name without extension (i.e. `Protomaps` again).
6975

70-
Adds an `Open in pmtiles.io` button that allows to open Protomaps PMTiles files on <https://pmtiles.io>.
76+
Lastly, add the import name to the list of exports, e.g.
7177

7278
```js
73-
import Protomaps from './src/actions/assets/Protomaps.js';
74-
export default { Protomaps };
79+
export default {
80+
OtherAction,
81+
Protomaps
82+
};
7583
```
7684

85+
Save the file and rebuild / restart STAC Browser.
7786

87+
## Developer Guide
7888

79-
## Links
89+
Implementing actions for assets and links follows a very similar pattern.
90+
The main difference is that assets implement the [`AssetActionPlugin` interface](../src/actions/AssetActionPlugin.js) while links implement the [`LinkActionPlugin` interface](../src/actions/LinkActionPlugin.js).
91+
Similarly, actions for assets are stored in the folder links are stored in the folder [`src/actions/assets`](../src/actions/assets) while links are stored in the folder [`src/actions/links`](../src/actions/links).
8092

81-
All actions for links are stored in the folder [`src/actions/links`](../src/actions/links).
82-
They all implement the [`LinkActionPlugin` interface](../src/actions/LinkActionPlugin.js).
83-
The actions can be enabled by adding them to the [`linkActions.config.js`](../linkActions.config.js) file.
84-
85-
### Felt (Links)
86-
87-
Adds an `Open in Felt` button that allows to show XYZ tile services on <https://felt.com>.
88-
The link to the XYZ has to follow the [web-map-links extension](https://github.com/stac-extensions/web-map-links/blob/v1.0.0/README.md#xyz).
89-
90-
```js
91-
import Felt from './src/actions/links/Felt.js';
92-
export default { Felt };
93-
```
93+
The interfaces for both look as follows:
9494

95-
### pmtiles.io
95+
- `constructor(data: object, component: Vue, id: string)`
96+
- `data`: The asset or link object, it is available in the class throuh `this.asset` (for assets) and `this.link` (for links).
97+
- `component`: The parent Asset/Link Vue component (available in the class through `this.component`)
98+
- `id`: Internal ID of the asset or link, not meant to be used.
99+
- `get btnOptions() : object`
100+
- This should return an object of button options, see [VueBootstrap b-button](https://bootstrap-vue.org/docs/components/button/#component-reference) for details. Returns `href`, `rel` (only for links) and `target` (set to `_blank`) by default.
101+
- `get onClick() : function(event: MouseEvent)`
102+
- Returns a function that accepts a [MouseEvent](https://developer.mozilla.org/de/docs/Web/API/MouseEvent). This is the action to execute in case no `href` is set.
103+
- `get uri() : string`
104+
- Reurns the URL to use as `href` for the button/link. This should a valid URL that a browser can navigate to, including the asset or link URL as a query parameter or so.
105+
- `get show() : boolean`
106+
- Return `true` if the action should be shown for the given asset or link. Return `false` otherwise, default to `false`.
107+
- `get text() : string`
108+
- Returns the text that is displayed for the button, defaults to "Open". Should be using the [i18n methods](https://kazupon.github.io/vue-i18n/api/#methods) to localize the text.
109+
- `get icon() : Vue`
110+
- Returns a Vue component that should be the icon for the button. Defaults to `BIconBoxArrowUpRight`, see <https://bootstrap-vue.org/docs/icons#icons-1> and search for `arrow-up-right`.
96111

97-
Adds an `Open in pmtiles.io` button that allows to open Protomaps PMTiles files on <https://pmtiles.io>.
112+
Each action should at least implement custom behaviour for `uri`, `show` and `text`.
98113

99-
```js
100-
import Protomaps from './src/actions/assets/Protomaps.js';
101-
export default { Protomaps };
102-
```
114+
It is recommended to inspect the existing actions to get an impression of what is possible and how it is implemented.
103115

104-
### OGC3dTiles
116+
Some notes:
105117

106-
Adds an `Open in Geofox.ai` button that allows to open OGC 3D Tiles files on <https://viewer.geofox.ai> or Cesium Sandcastle.
118+
- It is recommended to use [urijs](https://www.npmjs.com/package/urijs) for URL manipulations, it comes packages with STAC Browser anyway.
119+
- It can be helpful to use the Vue component that is available through `this.component`, for example:
120+
- `this.component.href` is the absolute asset URL (while `this.asset.href` could be relative or absolute)
121+
- `this.component.isBrowserProtocol` returns whether it's a http/https URL
122+
- `this.asset.type` / `this.link.type` contains the media type of the asset/link
107123

108-
```js
109-
import OGC3dTiles from './src/actions/assets/OGC3dTiles.js';
110-
export default { OGC3dTiles };
111-
```
124+
To enable a newly implemented action in STAC Browser, please follow the [User Guide](#user-guide).

‎docs/options.md‎

Lines changed: 43 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Options
1+
# Options <!-- omit in toc -->
22

33
STAC Browser exposes a wide variety of configuration options.
44
The following options can be provided in various ways to STAC Browser, either when running it or when building it.
@@ -14,48 +14,48 @@ The following ways to set config options are possible:
1414
Then run the build procedure and after completion, you can fill the `dist/config.js` with any options that you want to customize.
1515

1616
**The following options are available:**
17-
- [Options](#options)
18-
- [catalogUrl](#catalogurl)
19-
- [catalogTitle](#catalogtitle)
20-
- [allowExternalAccess](#allowexternalaccess)
21-
- [allowedDomains](#alloweddomains)
22-
- [apiCatalogPriority](#apicatalogpriority)
23-
- [detectLocaleFromBrowser](#detectlocalefrombrowser)
24-
- [storeLocale](#storelocale)
25-
- [locale](#locale)
26-
- [fallbackLocale](#fallbacklocale)
27-
- [supportedLocales](#supportedlocales)
28-
- [historyMode](#historymode)
29-
- [`history`](#history)
30-
- [`hash`](#hash)
31-
- [pathPrefix](#pathprefix)
32-
- [stacProxyUrl](#stacproxyurl)
33-
- [buildTileUrlTemplate](#buildtileurltemplate)
34-
- [useTileLayerAsFallback](#usetilelayerasfallback)
35-
- [displayGeoTiffByDefault](#displaygeotiffbydefault)
36-
- [redirectLegacyUrls](#redirectlegacyurls)
37-
- [itemsPerPage](#itemsperpage)
38-
- [maxItemsPerPage](#maxitemsperpage)
39-
- [maxPreviewsOnMap](#maxpreviewsonmap)
40-
- [cardViewMode](#cardviewmode)
41-
- [cardViewSort](#cardviewsort)
42-
- [showKeywordsInItemCards](#showkeywordsinitemcards)
43-
- [showKeywordsInCatalogCards](#showkeywordsincatalogcards)
44-
- [showThumbnailsAsAssets](#showthumbnailsasassets)
45-
- [defaultThumbnailSize](#defaultthumbnailsize)
46-
- [crossOriginMedia](#crossoriginmedia)
47-
- [requestHeaders](#requestheaders)
48-
- [requestQueryParameters](#requestqueryparameters)
49-
- [socialSharing](#socialsharing)
50-
- [authConfig](#authconfig)
51-
- [API Keys](#api-keys)
52-
- [Example 1: HTTP Request Header Value](#example-1-http-request-header-value)
53-
- [Example 2: Query Parameter Value](#example-2-query-parameter-value)
54-
- [HTTP Basic](#http-basic)
55-
- [OpenID Connect](#openid-connect)
56-
- [Example](#example)
57-
- [preprocessSTAC](#preprocessstac)
58-
- [Example: Update root catalog](#example-update-root-catalog)
17+
18+
- [catalogUrl](#catalogurl)
19+
- [catalogTitle](#catalogtitle)
20+
- [allowExternalAccess](#allowexternalaccess)
21+
- [allowedDomains](#alloweddomains)
22+
- [apiCatalogPriority](#apicatalogpriority)
23+
- [detectLocaleFromBrowser](#detectlocalefrombrowser)
24+
- [storeLocale](#storelocale)
25+
- [locale](#locale)
26+
- [fallbackLocale](#fallbacklocale)
27+
- [supportedLocales](#supportedlocales)
28+
- [historyMode](#historymode)
29+
- [`history`](#history)
30+
- [`hash`](#hash)
31+
- [pathPrefix](#pathprefix)
32+
- [stacProxyUrl](#stacproxyurl)
33+
- [buildTileUrlTemplate](#buildtileurltemplate)
34+
- [useTileLayerAsFallback](#usetilelayerasfallback)
35+
- [displayGeoTiffByDefault](#displaygeotiffbydefault)
36+
- [redirectLegacyUrls](#redirectlegacyurls)
37+
- [itemsPerPage](#itemsperpage)
38+
- [maxItemsPerPage](#maxitemsperpage)
39+
- [maxPreviewsOnMap](#maxpreviewsonmap)
40+
- [cardViewMode](#cardviewmode)
41+
- [cardViewSort](#cardviewsort)
42+
- [showKeywordsInItemCards](#showkeywordsinitemcards)
43+
- [showKeywordsInCatalogCards](#showkeywordsincatalogcards)
44+
- [showThumbnailsAsAssets](#showthumbnailsasassets)
45+
- [defaultThumbnailSize](#defaultthumbnailsize)
46+
- [crossOriginMedia](#crossoriginmedia)
47+
- [requestHeaders](#requestheaders)
48+
- [requestQueryParameters](#requestqueryparameters)
49+
- [socialSharing](#socialsharing)
50+
- [authConfig](#authconfig)
51+
- [API Keys](#api-keys)
52+
- [Example 1: HTTP Request Header Value](#example-1-http-request-header-value)
53+
- [Example 2: Query Parameter Value](#example-2-query-parameter-value)
54+
- [HTTP Basic](#http-basic)
55+
- [OpenID Connect](#openid-connect)
56+
- [Example](#example)
57+
- [preprocessSTAC](#preprocessstac)
58+
- [Example: Update root catalog](#example-update-root-catalog)
5959

6060
## catalogUrl
6161

‎src/actions/ActionPlugin.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { BIconBoxArrowUpRight } from 'bootstrap-vue';
22
import URI from 'urijs';
3+
import i18n from "../i18n";
34

45
export default class ActionPlugin {
56

@@ -41,4 +42,8 @@ export default class ActionPlugin {
4142
return BIconBoxArrowUpRight;
4243
}
4344

45+
get text() {
46+
return i18n.t('open');
47+
}
48+
4449
}

‎src/actions/assets/F3D.js‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,25 +21,17 @@ export default class F3D extends AssetActionPlugin {
2121
}
2222

2323
get uri() {
24-
// `https://f3d.app/web/#model=${modelUrl}` see PR merged for parsing model url and extension: https://github.com/f3d-app/f3d/pull/1596
24+
// `https://f3d.app/web/#model=${modelUrl}` see PR merged for parsing model url and extension:
25+
// https://github.com/f3d-app/f3d/pull/1596
2526
// Could enforce extension to help f3d.app determine the mesh type and loader to use
2627
let uri = new URI("https://f3d.app/web");
2728
uri.addQuery("model", this.component.href);
2829
uri = uri.toString().replace('?', '#');
2930
return uri;
3031
}
3132

32-
get uri_3dviewer() {
33-
// `https://3dviewer.net/#model=${modelUrl}` misconception, # is not a fragment but a query, can be replaced
34-
// let uri = new URI("https://3dviewer.net/");
35-
// uri.addQuery("model", this.component.href);
36-
// uri = uri.toString().replace('?', '#');
37-
let uri = `https://3dviewer.net/#model=${this.component.href.replace('%2F', '/')}`;
38-
return uri;
39-
}
40-
4133
get text() {
4234
return i18n.t('actions.openIn', {service: 'f3d.app'});
4335
}
4436

45-
}
37+
}

‎src/actions/assets/Geoparquet.js‎

Lines changed: 0 additions & 27 deletions
This file was deleted.

0 commit comments

Comments
 (0)