[UX Improvment] Getting-started with iTowns skeleton

linegallen commented 9 months ago

Context

In order to improve their experience with iTowns, users are widely included and have been interviewed to give their feedback and requirements. This process highlighted potential enhancements, needs or issues that can be solved by collaboration between users, UX designer and developers. All the following suggestions are based on interviews with users and discussions with iTowns teams.

Getting started with iTowns for a new project assumes that the user must write all setup files, even if he/she already did that for a former project. It can be inconvenient for some reasons :

Users consider this process as time-consuming. This is exacerbated when they have to do it for several small projects.
Significant errors can easily occur during the configuration process.

Furthermore, some users reported a complex first setup of iTowns.

Solution

We can improve and facilitate this getting-started user experience with a new Github repository. Thus, users could access with very few click a skeleton with the bare necessities to start every small project they want : demos, research or students projects.

The user will just have to fork and clone itowns-starter to begin iTowns handling.

The repository title is open to reconsideration with the community, given that I propose several repositories : one for each bundler supported by iTowns. We should start with webpack, considering that it’s one the most used.

Like a new project on Blender display a cube to manipulate, this skeleton would contains an empty globe-view 3D scene with international aerial imagery data. Ideally, it would also contain the DEM.

html et jvs would be on separate files
The code would not exceed a dozen lines. Sources, Layers and Views will be separated with a careful text formatting to keep it easy to understand and adapt.
There will be no Widgets.

To ensure this skeleton responds to the getting-started use-case, it should be tested with users to collect feedback.

This work will involve changes on the getting-started user journey. Then, it must be taken in consideration into the documentation, especially the "Preparing the webpage" section on each tutorials. The “how to run” and “How to use it in your project?” section will be impacted too.

Example

This following code snippet illustrates what the js file could contain.

import * as itowns from 'itowns';
import * as THREE from 'three';

// Get our `<div id="viewerId">` element. A canvas will be appended to this
// element when instanting a itowns' `View`.
const viewerDiv = document.getElementById('viewerDiv');

// Define an initial camera position
const placement = {
    coord: new itowns.Coordinates('EPSG:4326', 2.351323, 48.856712),
    range: 25000000,
};

// Create an empty globe View
const view = new itowns.GlobeView(viewerDiv, placement);

// Declare your source configuration, in this case the WMTS parameters of your
// requested resources.
const orthoConfig = {
    'url': '[https://wxs.ign.fr/decouverte/geoportail/wmts'](https://wxs.ign.fr/decouverte/geoportail/wmts%27),
    'crs': 'EPSG:3857',
    'format': 'image/jpeg',
    'name': 'ORTHOIMAGERY.ORTHOPHOTOS',
    'tileMatrixSet': 'PM',
};

// Instantiate the WMTS source of your layer
const imagerySource = new itowns.WMTSSource(orthoConfig);

// Create your imagery layer
const imageryLayer = new itowns.ColorLayer('imagery', {
    source: imagerySource,
});

// Add it to source view !
view.addLayer(imageryLayer);

jailln commented 9 months ago

Good idea :) There is a similar initiative with vite, made by an itowns user: https://github.com/dayjournal/itowns-starter

Desplandis commented 9 months ago

Good idea!

Following your issue and because I needed a basis for a demo, I tried to implement your proposal. There is however a couple of technical issues if we want a seamless experience:

2200
Multiple instances of Three.js being imported warning due to a duplication of this dependency. This can lead to multiple unexpected runtime errors (e.g. when using a custom renderer). This is caused by the webpack resolving three as a CJS module when imported by itowns and as an ESM module when imported by the final application.

iTowns / itowns