@panoramax/web-viewer

# Developing on the client You want to work on our library and offer bug fixes or new features ? That's awesome ! 🤩 Here are some inputs about working with Panoramax web client code. !!! note If something seems missing or incomplete, don't hesitate to contact us by [email](mailto:panoramax@panoramax.fr) or using [an issue](https://gitlab.com/panoramax/clients/web-viewer/-/issues). We really want Panoramax to be a collaborative project, so everyone is welcome (see our [code of conduct](https://gitlab.com/panoramax/clients/web-viewer/-/blob/develop/CODE_OF_CONDUCT.md)). ## Architecture The current code is split between various elements: - __Core components__: a single functional entry, like [Viewer](./reference/components/core/Viewer.md) (map + picture), [Photo Viewer](./reference/components/core/PhotoViewer.md) (picture only), [Coverage Map](./reference/components/core/CoverageMap.md) or [Editor](./reference/components/core/Editor.md). They share parts of code in [Basic](./reference/components/core/Basic.md) class. They specialized the behaviour of components depending on the needs. - __UI components, menus & widgets__: reusable web components, like [Map](./reference/components/ui/Map.md), [Photo](./reference/components/ui/Photo.md) or [Loader](./reference/components/ui/Loader.md). They are used in some views depending of the context. - __Utils__: utility functions, split into various files for clarity. ![Class diagram of Panoramax web viewer](./images/class_diagram.jpg) The library is relies on various other libraries: - [Lit](https://lit.dev/), for web components management - [Photo Sphere Viewer](https://github.com/mistic100/Photo-Sphere-Viewer), for displaying classic and 360° pictures - [Maplibre GL JS](https://github.com/maplibre/maplibre-gl-js), for displaying the map which shows sequences and pictures location - [JS Library Boilerplate](https://github.com/hodgef/js-library-boilerplate), for having a ready-to-use development toolbox ## Good to know ### Components `z-index` In order to offer a coherent overlay of widgets, we follow this general `z-index` ordering: | Component type | Z-Index | |-----------------------------------|:-------:| | MapLibre GL & Photo Sphere Viewer | <= 110 | | Widgets / Cornered Grid's corners | 120 | | Togglable menus | 130 | | Fullscreen loaders & popups | 200 | ### Parameters handling !!! note This concerns only __Viewer__ component. Editor & Coverage Map read input parameters only from Web Components attributes. Viewer component can read parameters from 3 different sources: - Web Component __attributes__, passed through DOM - Browser __local storage__ - __URL search__ parameters This allows a flexible way to interact with viewer for users. Prioritization of parameters is managed by [InitParameters class](./reference/utils/InitParameters.md), URL parameters coming first, then local storage, to fallback with Web component attributes (and eventually some hard-coded defaults). This means that, when developing, if you want to check if your attributes are well-defined, you may want to get rid of URL search parameters, as well as remove the `pnx-map-parameters` local storage item. Otherwise, they may not be read as they are lower priority than others. ### Third-party services URL All third-party services URL (like geocoding API, OSM iD editor) are grouped into a dedicated `src/utils/services.js` file. You can easily change them to deploy a custom version of the viewer. ### Presets for semantics The semantics system for sequences, pictures and annotations make use of __tagging presets__. These are JSON files hosted at [presets.panoramax.fr](https://presets.panoramax.fr/), they have their [dedicated Gitlab repository](https://gitlab.com/panoramax/server/tagging-presets). In the viewer, they show up through icons and translated labels associated to pictures & annotations. If you want to change them, you have to edit them in Gitlab repository. Viewer automatically loads hosted files at start. ### Rendering on mobile In order to improve performance, the 3D sphere used for projecting the picture on mobile has a lower amount of polygons, meaning a bit of distortions can appear on-screen. This is directly linked to [PSV Equirectangular adapter's resolution parameter](https://photo-sphere-viewer.js.org/guide/adapters/equirectangular.html#resolution). ![Comparative of mobile vs PC rendering](./images/comparative_3drender.jpg) ## Testing We're trying to make Panoramax as reliable and secure as possible. To ensure this, we rely heavily on code testing. A variety of testing tools is made available: * `npm start` : launches a dev web server on [localhost:3000](http://localhost:3000) * `npm run test` : unit testing * `npm run lint` : syntax checks * `npm run coverage` : amount of tested code If you're working on bug fixes or new features, please __make sure to add appropriate tests__ to keep Panoramax level of quality. ### Example pictures As Panoramax accepts all kind of picture, we have a large variety of troubles that can come to display them. Here is a list of very different images (various types, orientation, metadata) that can be useful to check if your rendering is working well: | UUID | Type | Heading | Comment | |----------------------------------------|----------------|---------|-------------------------------------| | `5bada38c-7cbc-4c81-a4d1-e39480fbec0b` | flat landscape | SE | | | `1d86cbbe-2293-4759-a4b6-23a815c49364` | flat portrait | SW | | | `f21d15a7-7a48-4194-bef2-09f22db03225` | flat square | NW | roll/pitch | | `b13976d5-fb07-44be-b6b6-2a2356a23cb8` | 360° | W | | | `db208199-10d9-4f32-869c-f5249194dac8` | 360° | NE | pose yaw/roll/pitch (Theta S) | | `234cebbe-2d4f-4294-8e13-2def46155b67` | 360° | E | pose roll/pitch (Theta 9) | | `03f220b4-28b2-4104-bc64-bb9e41a8aa5d` | 360° | W | picture tags + annotations | | `2f842858-2ada-4a25-a462-8d3bf256aca8` | H-cropped 360° | - | annotations | | `66dbf066-cf13-4fe3-a32a-2210daaeb45d` | H-cropped 360° | ? | | | `adf47cb2-cddd-4a8b-a5c9-f64248b62f90` | H-cropped 360° | SW | | | `193245fa-3454-492a-b0fc-aa06feab772e` | 180° | SE | | ## Documentation The documentation is a mix of: - [JSDoc comments](https://jsdoc.app/about-getting-started) embed directly in source files, and exported in `docs/reference/` folder - Higher-level docs as Markdown files, in `docs/` folder. The JSDoc can be exported as Markdown using this command: ```bash npm run doc ``` And all documentation can be previewed or built using [Mkdocs](https://www.mkdocs.org/): ```bash pip install mkdocs mkdocs-material mkdocs serve mkdocs build ``` Online versions are available at: - [docs.panoramax.fr](https://docs.panoramax.fr/web-viewer/) for __stable__ version - [viewer.geovisio.fr/docs](https://viewer.geovisio.fr/docs/) for __develop__ version ## Make a release See [dedicated documentation](./90_Releases.md).