From 128836c8cd126df21ffd5de5ca9701a13aa7645d Mon Sep 17 00:00:00 2001 From: Luc Claustres Date: Fri, 29 Nov 2024 08:04:49 +0000 Subject: [PATCH] Docs built from 911bb149a4004337f2985f964189fd9b796141d0 --- 404.html | 2 +- about/contact.html | 2 +- about/contributing.html | 2 +- about/introduction.html | 2 +- about/license.html | 2 +- about/roadmap.html | 2 +- assets/guides_advanced-usage.md.nFxwYRbl.js | 167 ++++++++++++++++++ .../guides_advanced-usage.md.nFxwYRbl.lean.js | 1 + guides/advanced-usage.html | 20 +-- guides/customizing-kano.html | 2 +- guides/getting-started.html | 2 +- guides/installing-kano.html | 2 +- guides/installing-services.html | 2 +- guides/kano-api.html | 2 +- guides/understanding-kano.html | 2 +- hashmap.json | 2 +- history.html | 2 +- index.html | 2 +- reference/api.html | 2 +- reference/configuration.html | 2 +- 20 files changed, 195 insertions(+), 27 deletions(-) create mode 100644 assets/guides_advanced-usage.md.nFxwYRbl.js create mode 100644 assets/guides_advanced-usage.md.nFxwYRbl.lean.js diff --git a/404.html b/404.html index eb26ad86..9d6a28fe 100644 --- a/404.html +++ b/404.html @@ -17,7 +17,7 @@
Kano

Appearance

404

PAGE NOT FOUND

But if you don't change your direction, and if you keep looking, you may end up where you are heading.
Take me home

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/about/contact.html b/about/contact.html index faa668c6..286bfc2b 100644 --- a/about/contact.html +++ b/about/contact.html @@ -20,7 +20,7 @@
Kano

Appearance

Contact ​

Please feel free to join our slack channel using the invitation link.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/about/contributing.html b/about/contributing.html index 6246a70f..f45eb15e 100644 --- a/about/contributing.html +++ b/about/contributing.html @@ -20,7 +20,7 @@
Kano

Appearance

Contributing ​

Submission guidelines ​

Report a bug ​

Before creating an issue please make sure you have checked out the docs, you might want to also try searching Github. It's pretty likely someone has already asked a similar question.

Issues can be reported in the issue tracker.

Pull Requests ​

We love pull requests and we're continually working to make it as easy as possible for people to contribute.

We prefer small pull requests with minimal code changes. The smaller they are the easier they are to review and merge. A core team member will pick up your PR and review it as soon as they can. They may ask for changes or reject your pull request. This is not a reflection of you as an engineer or a person. Please accept feedback graciously as we will also try to be sensitive when providing it.

Although we generally accept many PRs they can be rejected for many reasons. We will be as transparent as possible but it may simply be that you do not have the same context or information regarding the roadmap that the core team members have. We value the time you take to put together any contributions so we pledge to always be respectful of that time and will try to be as open as possible so that you don't waste it.

Commit message guidelines ​

We follow the Conventional commits specifications which provides a set of rules to make commit messages more readable when looking through the project history. But also, we use the git commit messages to generate the change log.

Commit message format ​

The commit message should be structured as follows:

<type>: <subject> [optional `breaking`]

Where type must be one of the following:

  • build: changes that affect the build system (external dependencies)
  • ci: changes to our CI configuration files and scripts
  • chore: changes that affect the project structure
  • docs: changes that affect the documentation only
  • feat: a new feature
  • fix: a bug fix
  • perf: a code change that improves performance
  • refactor: a code change that neither fixes a bug nor adds a feature
  • revert: revert changes
  • style: changes that do not affect the meaning of the code (lint issues)
  • test: adding missing tests or correcting existing tests

Use the optional [ breaking ] keyword to declare a BREAKING CHANGE.

Examples ​

  • Commit message with description and breaking change in body
feat: allow provided config object to extend other configs [ breaking ]
  • Commit message with no body
docs: correct spelling in the contributing.md file
  • Commit message for a fix using an issue number.
fix: fix minor issue in code (#12)

Versioning guidelines ​

We rely on Semantic Versioning for versioning a release. Indeed, given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make a major evolution leading to breaking changes,
  • MINOR version when you add functionality in a backwards-compatible manner
  • PATCH version when you make backwards-compatible bug fixes.

The command npm run release:<type>, where <type> is either patch, minor or major, helps you to do the release.

It performs the following task for you:

  • increase the package version number in the package.json file
  • generate the change log
  • create a tag accordingly in the git repository and push it

Contributor Code of Conduct ​

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0, available at http://contributor-covenant.org/version/1/0/0/

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/about/introduction.html b/about/introduction.html index 1f64d2d4..0fad7177 100644 --- a/about/introduction.html +++ b/about/introduction.html @@ -20,7 +20,7 @@
Kano

Appearance

Introduction ​

Kano is a powerful application that can be used to visualize any time-varying geospatial data, notably served by Kargo.

kano-screenshot

TIP

This application is based on the Kalisio Development Kit.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/about/license.html b/about/license.html index d93b44de..af99effc 100644 --- a/about/license.html +++ b/about/license.html @@ -20,7 +20,7 @@
Kano

Appearance

License ​

MIT License

Copyright (c) 2017-202x Kalisio

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/about/roadmap.html b/about/roadmap.html index 5cb363d8..d38579a6 100644 --- a/about/roadmap.html +++ b/about/roadmap.html @@ -20,7 +20,7 @@
Kano

Appearance

Roadmap ​

The roadmap is available on Github.

Milestones ​

The milestones are available on Github

Release Notes ​

The changelog is available in Github

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/assets/guides_advanced-usage.md.nFxwYRbl.js b/assets/guides_advanced-usage.md.nFxwYRbl.js new file mode 100644 index 00000000..1997bde8 --- /dev/null +++ b/assets/guides_advanced-usage.md.nFxwYRbl.js @@ -0,0 +1,167 @@ +import{_ as a,c as e,J as n,V as s,E as t,o as l}from"./chunks/framework.J61Sinzt.js";const u=JSON.parse('{"title":"Advanced usage","description":"","frontmatter":{"sidebarDepth":3},"headers":[],"relativePath":"guides/advanced-usage.md","filePath":"guides/advanced-usage.md"}'),h={name:"guides/advanced-usage.md"},p=s('

Advanced usage ​

Integrating Kano ​

To avoid the burden of developing a completely new application for every mapping needs you might have, Kano provides you with the capabilities to be integrated in your web application as an <iframe/> like this:

',3),k=s(`

This iframe offers an API so that you can dynamically control the behaviour and the content of Kano, as well as how the embedding application reacts in real-time to changes in Kano, a.k.a micro frontend. You can read more about the underlying concepts in this article.

The API is a subset of the internal Kano components and uses post-robot to

  1. select which is the target component
    • event name = map for 2D map and globe for 3D globe
  2. transform external method calls to internal calls using the following event payload
    • the command property is the mixin method name (e.g. isLayerVisible)
    • the args property is the expected method arguments (e.g. a string, an object or an array when multiple arguments are required)
  3. retrieve internal method call result externally
    • event response data is the method result object
  4. retrieve internal property externally
    • the property property is the internal property name (e.g. layers)
    • event response data is the returned property value

TIP

Event messaging using post-robot is always async because it relies on the postMessage API under-the-hood.

WARNING

In-memory data exchange is Json and more specifically GeoJson for map features. Do not try to inject functions or "complex" objects (e.g. class instances) in event payloads.

WARNING

You must use the same version of the post-robot library as the one used by Kano. For now, Kano relies on the 10.0.42 version of post-robot.

In addition to the commands used to access mixin methods there are a couple of dedicated commands listened by Kano to:

The following keys can be set in local storage to alter the application behaviour:

Here is a simple code sample:

html
  <script src="https://cdn.jsdelivr.net/npm/post-robot@10.0.10/dist/post-robot.min.js"></script>
+  <iframe id="kano" title="Kano" allow="geolocation *" style="width: 1024px; height: 768px;" src="kano.kalisio.com">
+  <script>
+    var kano = document.getElementById('kano').contentWindow
+    // Wait for Kano to be initialized
+    postRobot.on('kano-ready', function() {
+      // Optionnaly overrides default setup of Kano
+      postRobot.send(kano, 'setConfiguration', { 'appName': 'xxx' })
+      .then(function() {
+      // Optionnaly set a valid token to avoid authentication
+      return postRobot.send(kano, 'setLocalStorage', { 'xxx-jwt': 'yyy' })
+    })
+      .then(function() {
+      // Show and zoom to a layer
+      return postRobot.send(kano, 'map', { command: 'showLayer', args: 'Layer name' })
+    })
+    .then(function() {
+        return postRobot.send(kano, 'map', { command: 'zoomToLayer', args: 'Layer name' })
+      })
+    .then(function() {
+        return postRobot.send(kano, 'map', { property: 'layers' })
+      })
+    .then(function(result) {
+        console.log('Layer list', result.data)
+      })
+    })
+  </script>

A full sample exploring the different ways to interact with the API is provided here. When running the demo you can dynamically call API methods when toggling the different buttons on the left.

WARNING

Depending on the configuration of your Kano instance some features might not work as expected in the sample as it relies on some specific layers to exist.

Listening to events ​

There are a lot of events to be listened by integrating application to be aware of Kano internal states or user behaviour.

WARNING

You should add a listener for each event in your application, even if you don't need to do any processing, otherwise the post-robot library will raise a warning.

Frontend events ​

The following ones are related to Kano states:

The following ones are related to layers management:

The layer-add and layer-update events are particular as it might expect a response, in this case the altered data will be taken into account instead of the original data when updating the layer:

js
postRobot.on('layer-add', (event) => {
+    const layer = event.data
+    if (layer.name === 'MyLayer') {
+      // Update the layer, eg change the data filter
+      Object.assign(layer.baseQuery, { 'properties.user': 'MyUser' })
+      return layer
+    }
+  })
+postRobot.on('layer-update', (event) => {
+    const { name, geoJson } = event.data
+    if (name === 'MyLayer') {
+      const features = geoJson.features || [geoJson]
+      return {
+        type: 'FeatureCollection',
+        features: features.map(feature => {
+          // Update the features
+          ...
+        })
+      }
+    }
+  })

The following ones are related to user interaction (mouse or gesture):

Most user interaction events will provide you with the following properties as data payload:

TIP

For touch events the former properties at root level of the data payload are related to the first touch point (ie single-touch gesture). If you'd like to get information about all touch points for multi-touch gesture you will similarly get longitude, latitude, containerPoint and layerPoint values for all touch points in touches, changedTouches and targetTouches arrays relating to the same original touch event properties.

By default only click, dbclick and contextmenu events are sent and you should enable more (respectively disable), using the allowForwardEvents (respectively disallowForwardEvents) configuration option:

js
postRobot.send(kano, 'setConfiguration', {
+  // Allow more events to be emitted
+  'mapActivity.allowForwardEvents': ['mouseover', 'mouseout', 'mousemove', 'contextmenu']
+  // Do not receive these events
+  'mapActivity.disallowForwardEvents': ['mousemove']
+})
+// React to right-click (similar for others events like mouseover, mouseout, mousemove)
+postRobot.on('contextmenu', (event) => {
+  const { latitude, longitude, feature, layer, containerPoint } = event.data
+  const { x, y } = containerPoint
+  if (feature) {
+    // The event targets a feature from a layer
+  } else {
+    // Otherwise the event targets the map background
+  }
+})

TIP

A feature can be tagged to stop events propagation, either immediate or not, by specifying it in style:

js
{
+    type: 'Feature',
+    …
+    style: { stopImmediatePropagation: ['mousedown', 'touchmove'] }
+}

This can be used to e.g. prevent the map to be dragged when touching a specific fetaure.

The following events are related to geometry editing:

TIP

A point feature can be tagged as draggable by specifying it in style:

js
{
+    type: 'Feature',
+    …
+    style: { draggable: true }
+}

To drag line or polygon vertices you should use the geometry editor.

The following events are related to map state changes and do not provide additional properties like interaction events:

Backend events ​

Backend service events can be listened by integrating application, in this case the serviceEvent property, respectively the data property, contains the service event name, respectively service event data, in the post-robot event payload:

For instance, you can listen to changes in the catalog service like this:

js
  postRobot.on('catalog', (event) => {
+    const { serviceEvent, data } = event.data
+    console.log(\`Received \${serviceEvent} catalog event\`)
+  })

Kano also provides you with an internal event bus service called events that can be used to dispatch custom events to all connected clients. This service internally has only a create method to send events, you can send a custom event named item-selected through this service like this:

js
  // Tell others clients selection changed
+  await postRobot.send(kano, 'event', {
+    name: 'item-selected', data: { id: item.id }
+  })

Others clients can listen to this custom event like this:

js
  // Listen to selection change
+  postRobot.on('item-selected', (event) => {
+    const { id } = event.data
+    ...
+  })

Accessing the underlying API ​

You can access the backend API using either the Feathers client or raw HTTP REST requests. However, in order to ease integration you can also access the backend API through the iframe API. For this simply target the api component using post-robot, which transform external method calls to internal calls using the following event payload:

Event response data is the method result object. In addition to the event used to access service operations the api-ready event is to be listened by integrating application to know when the Kano backend API has been initialized in the iframe so that you can safely use it.

Here is a simple code sample:

html
  <script src="https://cdn.jsdelivr.net/npm/post-robot@10.0.10/dist/post-robot.min.js"></script>
+  <iframe id="kano" title="Kano" allow="geolocation *" style="width: 1024px; height: 768px;" src="kano.kalisio.com">
+  <script>
+    var kano = document.getElementById('kano').contentWindow
+    // Wait for map to be initialized
+    postRobot.on('map-ready', () => {
+      // Request saved user contexts and activate the first one if any
+      postRobot.send(kano, 'api', { service: 'catalog', operation: 'find', args: [{ query: { type: 'Context' } }] })
+      .then((result) => {
+        const response = result.data
+        if (response.total > 0) postRobot.send(kano, 'map', { command: 'loadContext', args: response.data[0] })
+      })
+    })
+  </script>

Client-side hooks ​

As you cannot directly access the underlying Feathers services from the iframe, the API allows you to setup events to be sent whenever a hook is run. Upon event reception you will get hook items as input, can alter it and send it back as output. This way the original hook items will be altered as usual in Kano.

js
await postRobot.send(kano, 'hooks', {
+  service: 'catalog',
+  // Emitted event names can be changed, by default it will look like eg 'catalog-after-find-hook'
+  hooks: { after: { find: { name: 'catalog-loaded' } } }
+})
js
postRobot.on('catalog-loaded', (event) => {
+  const { items } = event.data
+  // Update items
+  items.forEach(item => {
+    ...
+  })
+  return items
+})

Developing in Kano ​

Kano is powered by the KDK and rely on its main abstractions. If you'd like to develop an application based on Kano or extend Kano we assume you are familiar with this technology. Indeed, Kano is based on the KDK and makes the best use of all the features offered by the provided cartographic components and services.

Add stickies ​

The most simple way to develop in Kano is to design and integrate your own components in the 2D or 3D activity. For this you simply have to

  1. Put you single-file component(s) in the src/components folder (e.g. MyComponent.vue)
  2. Update the configuration to declare your component(s) in the 2D/3D activity by adding a local.js in the config folder like this:
js
module.exports = {
+  mapActivity: { // Can also be globeActivity
+    stickies: {
+      content: [{
+        id: 'my-component', position: 'left', offset: [18, 0], content: [{ component: 'MyComponent' }]
+      }]
+    }
+  }
+}

Then build/run the application as usual.

The component file should look e.g. like this:

html
<template>
+  <div>
+    <q-dialog ref="myDialog">
+    </q-dialog>
+    <q-btn round color="primary" icon="edit_location" @click="showDialog">
+    </q-btn>
+  </div>
+</template>
+
+<script>
+export default {
+  name: 'my-component',
+  inject: ['kMap'],
+  data () {
+    return {
+      ...
+  },
+  methods: {
+    async showDialog () {
+      this.$refs.myDialog.show()
+    },
+    onTimeChanged () {
+      ...
+    }
+  },
+  async mounted () {
+    // To be aware of time change
+    this.kMap.$on('current-time-changed', this.onTimeChanged)
+    ...
+  },
+  beforeUnmount () {
+    this.kMap.$off('current-time-changed', this.onTimeChanged)
+  }
+}
+</script>
+// Required translations in JSON format
+<i18n>
+{ 
+  "fr": {
+      ...
+    }
+  },
+  "en": {
+      ...
+    }
+  }
+}
+</i18n>

It's also possible to create separated i18n files if you'd like, simply put your plugin_en.json, plugin_fr.json, etc. files in the src/i18n folder before building the app.

Add custom code ​

You can update the plugin.js entry point in the boot folder in order to insert your own features (functions, mixins, etc.). If you'd like to enhance the default activities provided by kano you can register your own mixins in this file by using the mixin store:

import { MixinStore } from '../mixin-store'
+import myMixin from '../my-mixin.js'
+
+MixinStore.set('my-mixin', myMixin)

Then add it to the configuration of the target activity in order to make Kano apply it automatically:

js
module.exports = {
+  mapActivity: { // Can also be globeActivity
+    additionalMixins: [ 'my-mixin' ],
+    ...
+  }
+}
`,71);function o(r,d,E,c,g,y){const i=t("kalisio-maps");return l(),e("div",null,[p,n(i),k])}const m=a(h,[["render",o]]);export{u as __pageData,m as default}; diff --git a/assets/guides_advanced-usage.md.nFxwYRbl.lean.js b/assets/guides_advanced-usage.md.nFxwYRbl.lean.js new file mode 100644 index 00000000..bcceca61 --- /dev/null +++ b/assets/guides_advanced-usage.md.nFxwYRbl.lean.js @@ -0,0 +1 @@ +import{_ as a,c as e,J as n,V as s,E as t,o as l}from"./chunks/framework.J61Sinzt.js";const u=JSON.parse('{"title":"Advanced usage","description":"","frontmatter":{"sidebarDepth":3},"headers":[],"relativePath":"guides/advanced-usage.md","filePath":"guides/advanced-usage.md"}'),h={name:"guides/advanced-usage.md"},p=s("",3),k=s("",71);function o(r,d,E,c,g,y){const i=t("kalisio-maps");return l(),e("div",null,[p,n(i),k])}const m=a(h,[["render",o]]);export{u as __pageData,m as default}; diff --git a/guides/advanced-usage.html b/guides/advanced-usage.html index c5169101..ffab466d 100644 --- a/guides/advanced-usage.html +++ b/guides/advanced-usage.html @@ -12,7 +12,7 @@ - + @@ -65,11 +65,7 @@ }) } } - })

The following ones are related to user interaction (mouse or gesture):

TIP

A feature can be tagged as draggable by specifying it in style:

js
{
-    type: 'Feature',
-    …
-    style: { draggable: true }
-}

Most user interaction events will provide you with the following properties as data payload:

TIP

For touch events the former properties at root level of the data payload are related to the first touch point (ie single-touch gesture). If you'd like to get information about all touch points for multi-touch gesture you will similarly get longitude, latitude, containerPoint and layerPoint values for all touch points in touches, changedTouches and targetTouches arrays relating to the same original touch event properties.

By default only click, dbclick and contextmenu events are sent and you should enable more (respectively disable), using the allowForwardEvents (respectively disallowForwardEvents) configuration option:

js
postRobot.send(kano, 'setConfiguration', {
+  })

The following ones are related to user interaction (mouse or gesture):

Most user interaction events will provide you with the following properties as data payload:

TIP

For touch events the former properties at root level of the data payload are related to the first touch point (ie single-touch gesture). If you'd like to get information about all touch points for multi-touch gesture you will similarly get longitude, latitude, containerPoint and layerPoint values for all touch points in touches, changedTouches and targetTouches arrays relating to the same original touch event properties.

By default only click, dbclick and contextmenu events are sent and you should enable more (respectively disable), using the allowForwardEvents (respectively disallowForwardEvents) configuration option:

js
postRobot.send(kano, 'setConfiguration', {
   // Allow more events to be emitted
   'mapActivity.allowForwardEvents': ['mouseover', 'mouseout', 'mousemove', 'contextmenu']
   // Do not receive these events
@@ -84,11 +80,15 @@
   } else {
     // Otherwise the event targets the map background
   }
-})

The following events are related to map state changes and do not provide additional properties like interaction events:

TIP

A feature can be tagged to stop events propagation, either immediate or not, by specifying it in style:

js
{
+})

TIP

A feature can be tagged to stop events propagation, either immediate or not, by specifying it in style:

js
{
     type: 'Feature',
     …
-    style: { stopImmediatePropagation: ['mousedown'] }
-}

Backend events ​

Backend service events can be listened by integrating application, in this case the serviceEvent property, respectively the data property, contains the service event name, respectively service event data, in the post-robot event payload:

For instance, you can listen to changes in the catalog service like this:

js
  postRobot.on('catalog', (event) => {
+    style: { stopImmediatePropagation: ['mousedown', 'touchmove'] }
+}

This can be used to e.g. prevent the map to be dragged when touching a specific fetaure.

The following events are related to geometry editing:

TIP

A point feature can be tagged as draggable by specifying it in style:

js
{
+    type: 'Feature',
+    …
+    style: { draggable: true }
+}

To drag line or polygon vertices you should use the geometry editor.

The following events are related to map state changes and do not provide additional properties like interaction events:

Backend events ​

Backend service events can be listened by integrating application, in this case the serviceEvent property, respectively the data property, contains the service event name, respectively service event data, in the post-robot event payload:

For instance, you can listen to changes in the catalog service like this:

js
  postRobot.on('catalog', (event) => {
     const { serviceEvent, data } = event.data
     console.log(`Received ${serviceEvent} catalog event`)
   })

Kano also provides you with an internal event bus service called events that can be used to dispatch custom events to all connected clients. This service internally has only a create method to send events, you can send a custom event named item-selected through this service like this:

js
  // Tell others clients selection changed
@@ -186,7 +186,7 @@
     ...
   }
 }
- + \ No newline at end of file diff --git a/guides/customizing-kano.html b/guides/customizing-kano.html index 96bda1a6..ad66cf43 100644 --- a/guides/customizing-kano.html +++ b/guides/customizing-kano.html @@ -515,7 +515,7 @@ -d @stations-data.json https://your.kano.domain/api/sensors-stations curl -X POST -H "Authorization: Bearer %TOKEN%" -H "Content-Type: application/json" ^ -d @observations-data.json https://your.kano.domain/api/sensors-observations

TIP

For testing purpose you can get a valid token from the local storage in the developer tool after logged into Kano.

Using the bottom timeline, navigate to a date/time with existing sensor data, you now should be able to see your sensor on the map, selecting it should open the value timeseries:

sensors layers

A data layer can contain multiple time-varying elements called variables. The features may contain additional properties, e.g. a status (OK/NOK), a name, etc. that can be used to customize the rendering, e.g. icon, color, tooltip, etc.

The main configuration options are the following:

TIP

A layer can have no fixed stations but only measurements from sensors in order to display moving data

Customizing the catalog legend ​

To be completed

- + \ No newline at end of file diff --git a/guides/getting-started.html b/guides/getting-started.html index 0dbe295e..1c827095 100644 --- a/guides/getting-started.html +++ b/guides/getting-started.html @@ -20,7 +20,7 @@
Kano

Appearance

Getting Started ​

Kano comes with small tutorials (a.k.a. tours) that can be directly run on the application in order to understand how its internal components can be used. You will first have to connect to make everything works as expected.

Then, you can launch the main tutorial directly from the main menu through the following icon . Follow the step by step guide , go back if required and stop anytime as illustrated by the following figure:

tour

From the main tutorial you can open others tutorials dedicated to specific components (like e.g. the navigation bar) whenever you see the icon.

WARNING

Kano look and features are ever-evolving, moreover it can be configured according to your specific use case. As a consequence, your screen probably looks a little different than what you can read and see in this documentation but the key concepts remain the same.

The main menu allows to open the documentation, manage your settings and logout from Kano.

👉 Launch the main tutorial from the main menu then open the link to the main menu tutorial to get more details

Application bar ​

The application bar allows to quickly execute recurring actions:

  • switch from 2D (respectively 3D) activity to 3D (respectively 2D) activity,
  • center the view on your current location and display it,
  • seek for an address,
  • manage your favorite views,
  • tools to e.g. display the coordinates of a location,
  • switch to fullscreen mode.

👉 Launch the main tutorial from the main menu then open the link to the navigation bar tutorial to get more details

Catalog ​

The catalog organises layers into different categories and comes with a set of built-in geospatial data (Catalog tab). However, you can complete it with your own spatial data (My data tab). The catalog allows to manage the layers displayed on your view. You can show/hide a layer by selecting it in the relevant category.

WARNING

The data of some layers are only visible starting from a given scale if there is too much data to ensure a readable and smvisualisation.

In this case the layer will be disable until you reach the required scale on the map (zoom in or zoom to the layer to do so).

Using the menu on a layer you can access available actions for this layer.

The catalog also displays your list of views (My views tab) and projects (My projects tab).

👉 Launch the main tutorial from the main menu then open the link to the catalog tutorial to get more details

Timeline ​

The timeline allows to quickly execute actions related to the time of the displayed data. Stick to real-time or go forward/backward in time as you wish.

👉 Launch the main tutorial from the main menu then open the link to the timeline tutorial to get more details

Floating action button ​

Using the FAB at the bottom right corner you can:

  • Create a new view to recall a given extent while activating some data layers.
  • Create a new blank data layer:
    • By connecting to web mapping services using OGC standards (WMS, WFS, TMS, WMTS).
    • By locating and drawing the underlying entities. You can add the data schema from a JSON schema file in order to edit the meatadata (i.e. properties) of your entities.
    • By import existing data from a GeoJSON file.
  • Create a new project for your users by selecting a set of layers and views.
  • Probe weather forecast data from active prediction models by selecting a specific location on the map.

👉 Launch the main tutorial from the main menu then open the link to the FAB tutorial to get more details

Contextual menu ​

A right-click on a feature of the map will display a contextual menu if some actions are available for the target element like editing the properties of a user-defined feature or remove it.

Layer actions ​

Depending on the layer different actions are available. The most common action is to zoom to the layer in order to fit the view on the available data. If the layer is disabled at high scales this action will set the current scale of the map so that data will start be visible if the layer is shown.

More actions are available on user-defined feature layers:

  • save the layer (i.e. make it persistent),
  • edit layer properties like its name or description,
  • edit layer features (metadata and geometry),
  • edit display style,
  • filter data according to metadata,
  • display raw data,
  • create charts,
  • delete the layer.

Projects ​

Users with permissions to manage the catalog (i.e. create, update, remove layers) can also create, update and remove projects. A project is a set of layers and views useful to cover a specific use case of your users.

When a user activates or opens a project by selecting it in the catalog, the current activity context will switch to only display layers and views available in the projects. A user can deactivate or close the current project using the icon in the application bar. He can also open another project using the dropdown project menu in the application bar.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/guides/installing-kano.html b/guides/installing-kano.html index a488b23d..adc19d4d 100644 --- a/guides/installing-kano.html +++ b/guides/installing-kano.html @@ -428,7 +428,7 @@ } ]

As detailed in the KDK documentation Kano comes into three different flavors. By default the helm chart targets the latest preproduction version (test tag) but you can change it to target either a development (dev tag) or a production (prod tag) release using the command line switch --set image.tag=prod.

WARNING

By default no built-in layers are available in Kano unless you specify their names using the LAYERS_FILTER environment variable. By defining LAYERS_FILTER=* you will get all built-in layers but take care that a lot of them requires additional services to work correctly (read following sections below). You can however directly add new layers using the Kano GUI (through the add layer button or by drag'n'drop on the map).

TIP

If you'd like to use the 3D mode or the Mapillary layer you should provide the required tokens to access their respective APIs on the backend side by setting the following environment variables: CESIUM_TOKEN, MAPILLARY_TOKEN.

To uninstall the Kano environment:

shell
kubectl delete all --all -n tutorial
 kubectl delete namespace tutorial

WARNING

Please note that it will not delete the associate PVC. If you want to remove it, use kubectl delete pvc <the_PVC_of_mongoDB_in_tutorial>.

- + \ No newline at end of file diff --git a/guides/installing-services.html b/guides/installing-services.html index 522512ad..67f392b1 100644 --- a/guides/installing-services.html +++ b/guides/installing-services.html @@ -113,7 +113,7 @@ export PORT="8084" export NODE_OPTIONS="--inspect-port=9234" yarn dev

Add k2 ​

Coming soon

- + \ No newline at end of file diff --git a/guides/kano-api.html b/guides/kano-api.html index e88792de..db5d4801 100644 --- a/guides/kano-api.html +++ b/guides/kano-api.html @@ -138,7 +138,7 @@ } ] }

Use case example ​

We used the Kano API to expose French nuclear power production data to a set of Grafana dashboards.

We first developed a Krawler job whose task is to scrap power production data and to push it into Kano's backing MongoDB database. On Kano's side, we added a layer declaring a feature service pointing on the database collections the Krawler job was populating. From that time, nuclear power production data was available for display in Kano. Here's what it looks like :

Nucler power production data in Kano

Once the collections started being populated, we looked for ways to connect Grafana to Kano's API endpoint. For this we used the Infinity Grafana datasource plugin allowing us to use it's JSON scrapping capabilities to feed Grafana. We created a JWT token for the datasource to be able to reach Kano's API. After creating dashboards and looking up some docs, we ended up with a set of synthetic dashboards:

Nuclear power production overview in GrafanaNuclear power production detail in Grafana

Overall, here's the architecture of the whole solution :

Whole use case architecture

- + \ No newline at end of file diff --git a/guides/understanding-kano.html b/guides/understanding-kano.html index a1343f50..5185653f 100644 --- a/guides/understanding-kano.html +++ b/guides/understanding-kano.html @@ -20,7 +20,7 @@
Kano

Appearance

Understanding Kano ​

Kano is a powerful geospatial visualizer supporting advanced visualization capabilities in 2D and 3D thanks to hardware acceleration with WebGL technology. Driven by today's most advanced web technologies, it also enables tracking your geospatial assets in real-time.

Although Kano is a web application for end-users, it has also been designed to be integrated in third-party business applications and customized by developers (check out advanced usage). Using a single and simple API, Kano provides developers with the capability to easily develop 2D and 3D geospatial applications (check out the API reference). Last but not least, Kano comes with a built-in configuration for a set of geospatial data (check out installation guide). However, you can complete it with your own spatial data.

You can read an introductory article and one about how you can extend its capabilities.

Key concepts ​

Here is a quick rundown of the key concepts to handle when you're just getting started with Kano or geographic information system (GIS). In a nutshell, like any other GIS tool, Kano can be used to map, analyze, and assess real-world problems based on data, which is spatial or geographical in nature.

To achieve this, Kano is composed of two main activities (i.e. entry point for interacting with the user on a given type of objects):

  • a 2D activity to visualise and interact with data on a standard paperless map in 2D,
  • a 3D activity to visualise data and interact with on a virtual globe in 3D.

The view of each activity can contain a basemap (i.e. a background context), a set of data layers (i.e. business specific data), an extent (i.e. the part of the Earth currently on the screen), and navigation tools to pan and zoom. A layer specifies how a geographic dataset is portrayed on the map or the globe. The final rendering supporting your use case can usually be assembled by adding a serie of layers.

A feature layer is a grouping of similar geographic elements, for example, buildings, cities, roads, earthquake epicenters, etc. Features can be points, lines, or polygons (i.e. vector data). Feature layers are most appropriate for visualizing your own data on top of your basemaps. Using Kano, you can view, save, edit and analyze your own features and their attributes. Moreover, you can include interactive pop-up windows with information about the features. Raster data, most commonly found in remotely sensed data, topographic data, satellite imagery, and aerial imagery, can also be visualized. For this, Kano can leverage OGC standards that use the internet to view, edit, manage and share geospatial data.

Kano manages both space and time information in order to visualize time-varying geospatial phenomena: tracking of moving objects, history of measures taken by a sensor, weather prediction over time, etc. When a layer displays a time-varying dataset you are able to navigate back and forward in time using a timeline to see the data at your requested date/time.

Global overview ​

The following figure depicts the default 2D activity and the main application components:

Components

TIP

The 3D view is pretty similar to the 2D activity except that some feature might not be yet available.

Each component can be shown/hidden through a handle on the different side of the view:

  • at the top to open the application bar,
  • at the bottom to open the timeline,
  • on the left to open the side/main menu,
  • on the right to open the catalog.

In addition, a floating action button is available in the bottom-right corner to perform some actions.

Check out now our quickstart guide for more details.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/hashmap.json b/hashmap.json index 61c91196..77f0ac99 100644 --- a/hashmap.json +++ b/hashmap.json @@ -1 +1 @@ -{"about_license.md":"qdb0yiyt","guides_understanding-kano.md":"kgvoQdRq","reference_api.md":"wWmT5Fzy","guides_customizing-kano.md":"ZXzEQUud","history.md":"N9EJmtb-","guides_kano-api.md":"17wWu8Z6","about_contributing.md":"Q-A41HE2","about_introduction.md":"ZchEHfVq","about_roadmap.md":"Tsa-l91W","guides_getting-started.md":"6pc9104C","reference_configuration.md":"H2fn7Ne6","about_contact.md":"MLWlmPcp","guides_installing-services.md":"dsJfA9g8","guides_installing-kano.md":"ju5qSgOm","index.md":"Xmx78NTg","guides_advanced-usage.md":"ar737nIi"} +{"about_introduction.md":"ZchEHfVq","guides_kano-api.md":"17wWu8Z6","guides_understanding-kano.md":"kgvoQdRq","reference_api.md":"wWmT5Fzy","reference_configuration.md":"H2fn7Ne6","guides_installing-services.md":"dsJfA9g8","guides_advanced-usage.md":"nFxwYRbl","about_contact.md":"MLWlmPcp","history.md":"N9EJmtb-","guides_getting-started.md":"6pc9104C","about_roadmap.md":"Tsa-l91W","index.md":"Xmx78NTg","about_contributing.md":"Q-A41HE2","guides_installing-kano.md":"ju5qSgOm","about_license.md":"qdb0yiyt","guides_customizing-kano.md":"ZXzEQUud"} diff --git a/history.html b/history.html index 0545ac32..5a70a85d 100644 --- a/history.html +++ b/history.html @@ -20,7 +20,7 @@
Kano

Appearance

Changelog ​

v2.3.0 - Unreleased ​

Major enhancements:
👉 Bumped NodeJS to v20,
👉 Bumped CI to GitHub Actions,
👉 Bumped CesiumJS to v1.117 (3D rendering engine),
👉 Added visibility style property that can be templated,
👉 Added leaflet-arrowheads plugin to be able to create layers with related options,
👉 Added ability to rotate the map with still some restrictions (weather, canvas and gradient path layers),
👉 Added support for layers targetting PMTiles,
👉 Added highlightable flag on layers,
👉 iframe integration can now register client-side hooks on services,
👉 iframe integration can now register a handler to manage real-time feature updates,
👉 iframe integration can now track an entity in globe,
👉 New map attribution component,
👉 Ability to stack multiple timeseries with multi-selection,
👉 Selecting features does not clean current probe anymore,
👉 Now possible to avoid opening a widget on feature selection,
👉 Now possible to configure pane z-index directly in layer definition,
👉 Now possible to configure custom content in about box,
👉 Imported GeoJson files can now include panes information,
👉 (Dis)Connection popup can be deactivated by configuration,
👉 Simplified domain management in client configuration.

Cartographic data enhancements:
👉 Enhanced rendering and legend of various data layer.

Major bug fixes:
✅ Right opener not accessible when opening the right pane on mobile device,
✅ PWA installation prompt visible in Firefox even if not built as a PWA,
✅ layer-updated event was missing in globe activities.

More details on GitHub for Kano and KDK.

v2.2.0 - March 1st, 2024 ​

Major enhancements:
👉 Enhanced layer styling capabilities,
👉 More ergonomic timeline component,
👉 Enhanced location components,
👉 Enhanced image capture component,
👉 Allow to assign multiple legends to a layer,
👉 Legend can now display information related to layer variables,
👉 Legend can now display external OWS legends,
👉 Emit catalog/feature service events for iframe integration,
👉 Emit disconnect/reconnect events for iframe integration,
👉 Allow to show/hide window controls,
👉 Add a better map scale,
👉 New events service that can be used to dispatch messages to all connected clients,
👉 Added mapping projects management.

Cartographic data enhancements:
👉 Enhanced rendering and legend of various data layer.

Major bug fixes:
✅ Search tool does not zoom when the result is not a point feature,
✅ Mapillary marker is not moving when navigating with the viewer,
✅ GSMap cloud cover layer not working anymore.

Major breaking changes for customized versions or iframe integration use cases:
💥 changed layer variable unit from units to unit,
💥 local storage keys now automatically prefixed by configured application name in kebab case (e.g. my-app-jwt for MyApp name),
💥 layout elements in client config are now prefixed by layout (e.g. layout.windows or layout.panes), 💥 simple style cannot be defined anymore in feature style property,
💥 engine/layer style definition (details).

More details on GitHub for Kano and KDK.

v2.1.0 - Septembre 25th, 2023 ​

Major enhancements:
👉 Migrated documentation to VitePress,
👉 Progressive Web App,
👉 Enhanced time input components,
👉 Enhanced window behavior with size policy and responsive controls,
👉 Real-time user data layer update for collaborative editing.

Major bug fixes:
✅ Sending updateLayer command in iframe API closes feature edition,
✅ Layer filters not correctly updated on tiled layers,
✅ Favorite view items do not expand in catalog,
✅ Bug report button not available in about dialog.

More details on GitHub for Kano and KDK.

v2.0.0 - June 29th, 2023 ​

Major enhancements:
👉 Bumped NodeJS to v16 and Feathers to v5,
👉 Bumped Quasar to v2 and VueJS to v3,
👉 Allow to create specific views from a layer,
👉 Redirect to target URL once connected,
👉 Provided a legend component.

Cartographic data enhancements:
👉 RTE generation data layer linked to new krawler job,
👉 ICOS atmosphjeric data layer linked to new krawler job.

Major bug fixes:
✅ Token without user ID not valid anymore to be used by iframe.

Major breaking changes for customized versions or iframe integration use cases:
💥 renamed configuration/layers/categories files to .cjs,
💥 backend configuration should comply with Feathers v5, e.g. authentication,
💥 need to prefix layout path by layout. in frontend configuration,
💥 default mode required for each layout element with content having multiple keys,
💥 window.widgets frontend configuration path changed to windows.top.widgets,
💥 static files moved from src/statics to public,
💥 internal event bus refactoring (on/off() replaced $on/off(), added $engineEvents for map engine events).

Check NodeJS documentation for problems related to ECMAScript modules. Check Quasar upgrade guide for problems related to Quasar v2/Vue v3.

More details on GitHub for Kano and KDK.

v1.6.0 - August 30th, 2022 ​

Major enhancements:
👉 Catalog layout now includes favorite views,
👉 Shapefile import is now supported,
👉 Catalog with more default categories.

Cartographic data enhancements:
👉 METAR data layer linked to new krawler job,
👉 Little Alert Box data layer.

Major bug fixes:
✅ Geodesic circles cut when exceeding the viewport,
✅ Some measure layers do not work anymore in 3D mode,
✅ Forbid the window to pop out of the screen when moving or scaling it,
✅ Memory leak in gradient path,
✅ Real-time layers not correctly updated when time changes,
✅ Impossible to remove min/max zoom levels once edited in the style,
✅ Hiding/Showing a layer does not take into account configuration changes,
✅ Popup active by default in layer style editor,
✅ Editing the style of a web service layer (eg WMTS) makes it disappear.

Major breaking changes for customized versions or iframe integration use cases:
💥 Default catalog categories moved from frontend to backend configuration.

More details on GitHub for Kano and KDK.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/index.html b/index.html index 0ad3c7ec..c43dc87c 100644 --- a/index.html +++ b/index.html @@ -20,7 +20,7 @@
Kano

Appearance

Kano

A powerful real-time Geovisualizer

Show me more →
kalisio-kano

Powerful Geovisualizer

Kano supports advanced visualization capabilities in 2D and 3D thanks to hardware acceleration with WebGL technology

Real-time oriented

Driven by today’s most advanced web technologies, Kano enables real-time tracking of your geospatial assets

Designed to be integrated and customized

Through a single API, Kano provides users with the capability to develop geospatial applications

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/reference/api.html b/reference/api.html index ab616d5e..aa3fb195 100644 --- a/reference/api.html +++ b/reference/api.html @@ -20,7 +20,7 @@
Kano

Appearance

Backend API ​

The externally exposed API of the internal Kano services comes from the one provided by the KDK:

Frontend API ​

The externally exposed API of the internal Kano components (2D map and 3D globe) comes from the one provided by the KDK:

Similarly, most of the internal mapping components come from the KDK.

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file diff --git a/reference/configuration.html b/reference/configuration.html index e121e51f..c4137065 100644 --- a/reference/configuration.html +++ b/reference/configuration.html @@ -20,7 +20,7 @@
Kano

Appearance

Configuration ​

The default backend configuration file can be found here.

Most options come from the "standard" backend configuration of KDK based app.

The default frontend configuration file can be found here.

Most options come from the "standard" frontend configuration of KDK based app, here are the main ones:

  • appName: displayed application name,
  • appLogo: displayed application logo,
  • theme: the theme to be used,
  • screens: connection screens configuration
    • banner: displayed application banner,
    • login: login screen configuration
      • providers: array of OAuth2 providers to be used (like ['google', 'github']),
      • links: links displayed at the bottom of the screen,
    • logout: logout screen configuration
      • links: links displayed at the bottom of the screen,
    • changeEndpoint: change endpoint screen configuration (only useful for mobile apps)
      • links: links displayed at the bottom of the screen,
  • layout: layout configuration (see Quasar docs for details)
    • welcome: true to display the welcome screen by default,
    • topPane: application bar setup,
      • opener: true to add a handler to open/close the pane,
      • visible: true to show this pane,
    • leftPane: left pane (i.e. main menu) setup (as above),
    • bottomPane: bottom pane setup (as above),
    • rightPane: right pane setup (as above),
  • weacast: Weacast service
    • enabled: true to enable Weacast service. By default the service is enabled.
  • mapActivity: 2D map activity configuration
    • topPane: application bar components configuration
      • content: list of components to be displayed according to current mode,
      • filter: component filter using any expression supported by sift,
    • leftPane: left pane (i.e. main menu) components configuration
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • bottomPane: bottom pane components configuration
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • rightPane: right pane components configuration
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • page: page components configuration (can be used to add your own components)
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • window: window (i.e. widgets) configuration
      • widgets: list of widgets to be displayed,
      • filter: component filter using any expression supported by sift,
    • fab: floating action button (FAB) configuration
      • actions: list of actions to be displayed,
      • filter: action filter using any expression supported by sift,
    • catalog: 2D map layers panel configuration
      • filter: layer filter using any expression supported by sift,
      • categories: list of categories to be displayed in 2D map layers panel,
    • layers: 2D map layers configuration
      • actions: list of actions to be displayed,
      • filter: action filter using any expression supported by sift,
    • restore: user context restoration configuration
      • view: set it to true (default) in order to restore the current extent on page refresh
      • layers: set it to true (false by default) in order to restore the current visible layers on page refresh
    • engine: 2D map view configuration
  • globeActivity: 3D globe activity configuration
    • topPane: application bar components configuration
      • content: list of components to be displayed according to current mode,
      • filter: component filter using any expression supported by sift,
    • leftPane: left pane (i.e. main menu) components configuration
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • bottomPane: bottom pane components configuration
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • rightPane: right pane components configuration
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • page: page components configuration (can be used to add your own components)
      • content: list of components to be displayed,
      • filter: component filter using any expression supported by sift,
    • window: window (i.e. widgets) configuration
      • widgets: list of widgets to be displayed,
      • filter: component filter using any expression supported by sift,
    • fab: floating action button (FAB) configuration
      • actions: list of actions to be displayed,
      • filter: action filter using any expression supported by sift,
    • catalog: 3D map layers panel configuration
      • filter: layer filter using any expression supported by sift,
      • categories: list of categories to be displayed in 3D map layers panel,
    • layers: 3D map layers configuration
      • actions: list of actions to be displayed,
      • filter: action filter using any expression supported by sift,
    • catalog: 3D globe layers panel configuration
      • filter: layer filter using any expression supported by sift,
      • categories: list of categories to be displayed in 3D globe layers panel,
    • restore: user context restoration configuration
      • view: set it to true (default) in order to restore the current extent on page refresh
      • layers: set it to true (false by default) in order to restore the current visible layers on page refresh
    • engine: 3D globe view configuration

MIT Licensed | Copyright © 2017-20xx Kalisio

- + \ No newline at end of file