Merge branch 'main' into ol-stac

Author: m-mohr

README.md

@@ -8,7 +8,7 @@ implemented as a single page application (SPA) for ease of development and to
 limit the overall number of catalog reads necessary when browsing (as catalogs
 may be nested and do not necessarily contain references to their parents).
 
-Version: **3.3.3** (supports all STAC versions between 0.6.0 and 1.1.0)
+Version: **3.3.4** (supports all STAC versions between 0.6.0 and 1.1.0)
 
 This package has also been published to npm as [`@radiantearth/stac-browser`](https://www.npmjs.com/package/@radiantearth/stac-browser).
 
@@ -123,6 +123,7 @@ You need to change the [`locale`](docs/options.md#locale) and [`supportedLocales
 
 The following languages are currently supported:
 
+- Arabic `ar`
 - German `de` (Germany `de`, Switzerland `de-CH`)
 - Spanish `es`
 - English `en` (International `en`, US `en-US`, UK `en-GB`)
@@ -143,6 +144,7 @@ The following contributors kindly provide the translations:
 - [@m-mohr](https://github.com/m-mohr): `de`, `en`, `en-GB`, `en-US`
 - [@p1d1d1](https://github.com/p1d1d1): `de-CH`, `fr-CH`, `it`, `it-CH`
 - [@psacra](https://github.com/psacra): `pt`
+- [@randa-11295](https://github.com/randa-11295): `ar`
 - [@rnanclares](https://github.com/rnanclares): `es`
 - [@uba](https://github.com/uba): `pt-BR`
 

assetActions.config.js

@@ -4,7 +4,6 @@ import CopcViewer from './src/actions/assets/CopcViewer.js';
 import F3D from './src/actions/assets/F3D.js';
 import GeoJsonIo from './src/actions/assets/GeoJsonIo.js';
 // import Geofox from './src/actions/assets/Geofox.js';
-// import Geoparquet from './src/actions/assets/Geoparquet.js';
 // import Potree from './src/actions/assets/Potree.js';
 import Protomaps from './src/actions/assets/Protomaps.js';
 
@@ -14,7 +13,6 @@ export default {
   CopcViewer,
   F3D,
   GeoJsonIo,
-  // Geoparquet, // not ready yet
   // Potree,
   Protomaps,
-};
+};

config.js

@@ -9,6 +9,7 @@ module.exports = {
     fallbackLocale: "en",
     supportedLocales: [
         "de",
+        "ar",
 //      "de-CH",
         "es",
         "en",

docs/actions.md

@@ -1,120 +1,124 @@
-# Actions
+# Actions <!-- omit in toc -->
 
 STAC Browser has a pluggable interface to share or open assets and links with other services, which we call "actions".
 
 An action adds a button to an asset or link if certain requirements are met, which can then be executed by users.
 For example, you could open COPC files in a dedicated COPC Viewer, which otherwise you could only download.
 
-## Assets
+- [User Guide](#user-guide)
+  - [Assets](#assets)
+  - [Links](#links)
+- [Developer Guide](#developer-guide)
 
-All actions for assets are stored in the folder [`src/actions/assets`](../src/actions/assets).
-They all implement the [`AssetActionPlugin` interface](../src/actions/AssetActionPlugin.js).
-The actions can be enabled by adding them to the [`assetActions.config.js`](../assetActions.config.js) file.
-
-### cogeo.xyz
+## User Guide
 
-Adds an `Open in cogeo.xyz` button that allows to open Cloud-Optimized GeoTiff (COG) files on <https://cogeo.xyz>.
+### Assets
 
-```js
-import CoGeoXyz from './src/actions/assets/CoGeoXyz.js';
-export default { CoGeoXyz };
-```
+The following actions are available:
 
-### copc.io
+- `Cesium`: Allows to open OGC 3D Tiles (media type `application/3dtiles+json`) files through the Cesium Sandcastle at <https://sandcastle.cesium.com>.
+- `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>.
+- `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>.
+- `Felt`: Allows to open GeoTIFF, GeoJON and KML/KMZ files through Felt at <https://felt.com/map/>.
+- `Geofox`: Allows to open OGC 3D Tiles  (media type `application/3dtiles+json`) files through the 3D Assets Viewer at <https://viewer.geofox.ai>.
+- `GeoJsonIo`: Allows to open GeoJON files through [geojson.io](https://geojson.io).
+- `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/>.
+- `Protomaps`: Allows to open PMTiles (media type `application/vnd.pmtiles`) files through PMTiles Viewer at <https://pmtiles.io>.
 
-Adds an `Open in copc.io` button that allows to open Cloud-Optimized Point Cloud (COPC) files on <https://viewer.copc.io>.
-
-```js
-import CopcViewer from './src/actions/assets/CopcViewer.js';
-export default { CopcViewer };
-```
+All actions for assets are stored in the folder [`src/actions/assets`](../src/actions/assets) if you want to inspect them.
 
-### Felt (Assets)
-
-Adds an `Open in Felt` button that allows to import KML, KMZ, GeoTiff and GeoJSON assets to <https://felt.com>.
+The actions can be enabled by adding them to the [`assetActions.config.js`](../assetActions.config.js) file.
+Open the file and you'll see a number of imports and exports.
+Import the file for the action that you want to enable, e.g. for Felt:
 
 ```js
 import Felt from './src/actions/assets/Felt.js';
-export default { Felt };
 ```
 
-### geojson.io
+The path is fixed to `./src/actions/assets/`, the file extension is always `.js`.
+In-between add the file name from the list above.
+The import name should be the file name without extension (i.e. `Felt` again).
 
-Adds an `Open in geojson.io` button that allows to open GeoJSON files on <https://geojson.io>.
+Lastly, add the import name to the list of exports, e.g.
 
 ```js
-import GeoJsonIo from './src/actions/assets/GeoJsonIo.js';
-export default { GeoJsonIo };
+export default {
+  OtherAction,
+  Felt
+};
 ```
 
-### OGC3dTiles
-
-Adds an `Open in Geofox.ai` button that allows to open OGC 3D Tiles files on <https://viewer.geofox.ai> or Cesium Sandcastle.
-
-```js
-import OGC3dTiles from './src/actions/assets/OGC3dTiles.js';
-export default { OGC3dTiles };
-```
+Save the file and restart / rebuild STAC Browser.
 
-### geoparquet.info
+### Links
 
-Adds an `Open in geoparquet.info` button that allows to open GeoParquet files on <https://geoparquet.info>.
+The following actions are available:
 
-```js
-import Geoparquet from './src/actions/assets/Geoparquet.js';
-export default { Geoparquet };
-```
+- `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>.
+- `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/>.
+- `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>.
+- `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>.
 
-### potree.org
+All actions for assets are stored in the folder [`src/actions/links`](../src/actions/links) if you want to inspect them.
 
-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)
+The actions can be enabled by adding them to the [`linkActions.config.js`](../linkActions.config.js) file.
+Open the file and you'll see a number of imports and exports.
+Import the file for the action that you want to enable, e.g. for PMTiles / Protomaps:
 
 ```js
-import Potree from './src/actions/assets/Potree.js';
-export default { Potree };
+import Protomaps from './src/actions/links/Protomaps.js';
 ```
 
-### pmtiles.io
+The path is fixed to `./src/actions/links/`, the file extension is always `.js`.
+In-between add the file name from the list above.
+The import name should be the file name without extension (i.e. `Protomaps` again).
 
-Adds an `Open in pmtiles.io` button that allows to open Protomaps PMTiles files on <https://pmtiles.io>.
+Lastly, add the import name to the list of exports, e.g.
 
 ```js
-import Protomaps from './src/actions/assets/Protomaps.js';
-export default { Protomaps };
+export default {
+  OtherAction,
+  Protomaps
+};
 ```
 
+Save the file and rebuild / restart STAC Browser.
 
+## Developer Guide
 
-## Links
+Implementing actions for assets and links follows a very similar pattern.
+The main difference is that assets implement the [`AssetActionPlugin` interface](../src/actions/AssetActionPlugin.js) while links implement the [`LinkActionPlugin` interface](../src/actions/LinkActionPlugin.js).
+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).
 
-All actions for links are stored in the folder [`src/actions/links`](../src/actions/links).
-They all implement the [`LinkActionPlugin` interface](../src/actions/LinkActionPlugin.js).
-The actions can be enabled by adding them to the [`linkActions.config.js`](../linkActions.config.js) file.
+The interfaces for both look as follows:
 
-### Felt (Links)
+- `constructor(data: object, component: Vue, id: string)`
+  - `data`: The asset or link object, it is available in the class throuh `this.asset` (for assets) and `this.link` (for links).
+  - `component`: The parent Asset/Link Vue component (available in the class through `this.component`)
+  - `id`: Internal ID of the asset or link, not meant to be used.
+- `get btnOptions() : object`
+  - 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.
+- `get onClick() : function(event: MouseEvent)`
+  - 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.
+- `get uri() : string`
+  - 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.
+- `get show() : boolean`
+  - Return `true` if the action should be shown for the given asset or link. Return `false` otherwise, default to `false`.
+- `get text() : string`
+  - 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.
+- `get icon() : Vue`
+  - 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`.
 
-Adds an `Open in Felt` button that allows to show XYZ tile services on <https://felt.com>.
-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).
+Each action should at least implement custom behaviour for `uri`, `show` and `text`.
 
-```js
-import Felt from './src/actions/links/Felt.js';
-export default { Felt };
-```
+It is recommended to inspect the existing actions to get an impression of what is possible and how it is implemented.
 
-### pmtiles.io
+Some notes:
 
-Adds an `Open in pmtiles.io` button that allows to open Protomaps PMTiles files on <https://pmtiles.io>.
+- It is recommended to use [urijs](https://www.npmjs.com/package/urijs) for URL manipulations, it comes packages with STAC Browser anyway.
+- It can be helpful to use the Vue component that is available through `this.component`, for example:
+  - `this.component.href` is the absolute asset URL (while `this.asset.href` could be relative or absolute)
+  - `this.component.isBrowserProtocol` returns whether it's a http/https URL
+  - `this.asset.type` / `this.link.type` contains the media type of the asset/link
 
-```js
-import Protomaps from './src/actions/assets/Protomaps.js';
-export default { Protomaps };
-```
-
-### OGC3dTiles
-
-Adds an `Open in Geofox.ai` button that allows to open OGC 3D Tiles files on <https://viewer.geofox.ai> or Cesium Sandcastle.
-
-```js
-import OGC3dTiles from './src/actions/assets/OGC3dTiles.js';
-export default { OGC3dTiles };
-```
+To enable a newly implemented action in STAC Browser, please follow the [User Guide](#user-guide).