Feature/panoramax half-screen and full-map display modes for the minidock (V4)

library/api/panoramax/README.md

@@ -2,79 +2,140 @@
 
 _English below_
 
-Ce script permet d'afficher dans votre projet les photos provenant du projet Panoramax
-(https://panoramax.openstreetmap.fr/ et/ou https://panoramax.ign.fr/) dans Lizmap Web Client. À noter qu'il n'est pas
-nécessaire que votre projet soit dans une projection spécifique pour que ce script fonctionne. C'est QGIS qui se
-chargera de la reprojection.
+Ce script affiche dans Lizmap Web les photos du projet Panoramax (https://panoramax.fr). Les instances panoramax utilisées sont les instances IGN (https://panoramax.ign.fr) et OpenStreetMap France (https://panoramax.openstreetmap.fr).
 
-![alt text](image-3.png)
+![Panoramax dans Lizmap](image-3.png)
+
+Deux fichiers :
+
+- **`panoramax4_3.9.js`** : **VERSION RECOMMANDEE**. Utilise le web-viewer Panoramax V4 (Web Components) et crée lui-même les couches de points Panoramax dans la carte.
+- **`panoramax3_3.9.legacy.js`** : ancienne version basée sur l'API V3 et sur une couche Panoramax ajoutée dans le projet QGIS. Conservée pour référence, elle n'est plus maintenue et ne propose pas les modes d'affichage décrits plus bas.
 
 ## Pré-requis
 
-- Lizmap Web Client ≥ 3.8
+- Lizmap Web Client 3.9.
+- Le navigateur doit pouvoir joindre le CDN jsDelivr (web-viewer Panoramax 4.4.0), l'API `api.panoramax.xyz` et les serveurs de tuiles `panoramax.ign.fr` et `panoramax.openstreetmap.fr`.
+- Aucune couche Panoramax n'est nécessaire dans le projet QGIS : le script ajoute lui-même deux couches de tuiles vectorielles (IGN et OSM) à la carte quand le panneau est ouvert.
+- Aucune contrainte de projection : OpenLayers reprojette les tuiles à la volée.
 
-- Pour des raisons de performance et du fait qu'OpenLayers ne permette pas la reprojection de tuiles vectorielles,
-  **la ou les couches de données Panoramax doivent être ajoutées depuis votre projet QGIS**.
-  **Un groupe ou une couche nommée Panoramax doit absolument exister dans votre projet QGIS. Sinon le script générera
-  une erreur**. Vous pouvez changer le nom de votre couche/groupe mais dans ce cas il sera nécessaire de modifier
-  la variable `PANORAMAX_QGIS_LAYER_NAME` du script pour qu'elle corresponde au nom de votre couche. Vous pouvez
-  également modifier depuis QGIS le style de votre couche de tuiles vectorielles si vous le souhaitez.
+## Installation
 
-![alt text](image.png)
-![alt text](image-1.png)
+1. Copier `panoramax4_3.9.js` dans le dossier `media/js/default` du répertoire Lizmap (ou `media/js/nom_du_projet` pour un seul projet).
+2. Recharger la carte : un bouton avec une icône appareil photo apparaît dans la barre de gauche.
 
 ## Utilisation
 
-Pour utiliser le script Panoramax dans votre projet :
-1. assurez-vous d'avoir une couche Panoramax présente dans votre projet QGIS
-2. copier `panoramax_3.8.js` dans le dossier `media/js` de votre projet
-3. le bouton Panoramax s'affichera dans Lizmap Web Client
-4. En cliquant sur ce bouton, les photos associées aux points de la couche Panoramax seront affichées.
-   Un clic sur un point permet d'afficher la photo correspondante.
+1. Cliquer sur le bouton Panoramax : le minidock s'ouvre avec le visualiseur, et les points Panoramax s'affichent sur la carte.
+2. Cliquer sur un point : la photo correspondante s'affiche. Une flèche indique l'azimut de la vue et la carte se centre sur la photo.
+3. Naviguer dans les photos avec les flèches du visualiseur ou le lecteur sous l'image : la carte et la flèche suivent chaque photo.
+4. Fermer le minidock : les couches Panoramax sont masquées et la disposition revient à la normale.
+
+## Modes d'affichage (position minidock)
+
+Deux boutons en haut à droite du visualiseur Panoramax permettent de changer la disposition de la page :
+
+- **Moitié d'écran.** La zone carte est partagée entre la carte à gauche et les photos à droite. Il est possible de déplacer le séparateur entre les deux panneaux en faisant glisser celui-ci vers la droite ou vers la gauche (part de la carte entre 20 % et 80 %, 50 % par défaut). La carte continue de suivre la navigation dans les photos.
+
+  ![Mode moitié d'écran](half-panoramax.jpg)
+
+- **Pleine carte.** Les photos de Panoramax prennent toute la zone carte et la carte devient une vignette en bas à gauche, toujours centrée sur la photo courante. Un clic sur la vignette de la carte rétablit la disposition.
+
+  ![Mode pleine carte](full-panoramax.jpg)
+
+Un second clic sur le bouton actif, ou la fermeture du minidock, rétablit la disposition normale. On peut passer directement d'un mode à l'autre. Si un panneau Lizmap est ouvert (couches, impression, etc.), la carte et les photos se placent à sa droite et suivent son ouverture ou sa fermeture.
+
+Les deux modes sont masqués en affichage mobile et n'existent pas quand `DOCK_POSITION` vaut `dock`.
 
 ## Personnalisation
 
-Si vous modifiez le nom du groupe ou de la couche Panoramax dans QGIS, vous devrez adapter la variable
-`PANORAMAX_QGIS_LAYER_NAME` dans le script pour qu'elle corresponde au nom de la couche dans votre projet.
+Les constantes en tête du script, au-dessus de la ligne "DO NOT MODIFY BELOW THIS LINE" :
+
+| Constante | Rôle | Valeur par défaut |
+|---|---|---|
+| `DOCK_POSITION` | `minidock` ou `dock`. Les modes d'affichage n'existent qu'en `minidock` | `minidock` |
+| `DOCK_ICON`, `DOCK_TITLE` | Icône et titre du bouton | `icon-camera`, `Panoramax` |
+| `SPLIT_DEFAULT_PERCENT` | Part de la carte (à gauche) en moitié d'écran | `50` |
+| `SPLIT_MIN_PERCENT`, `SPLIT_MAX_PERCENT` | Bornes du séparateur | `20`, `80` |
+| `MAP_THUMBNAIL_WIDTH`, `MAP_THUMBNAIL_HEIGHT` | Taille de la vignette carte en pleine carte (px) | `240`, `160` |
+| `MAP_THUMBNAIL_MARGIN` | Distance de la vignette aux bords bas et gauche (px) | `20` |
+| `ARROW_ICON_SIZE`, `ARROW_ICON_COLOR` | Taille et couleur de la flèche d'azimut | `0.3`, `#e4e8e6` |
+| `PANORAMAX_INSTANCE` | API utilisée par le visualiseur | `https://api.panoramax.xyz/api` |
+| `CONTENT_TEXT` | Textes du panneau et des boutons, par langue (fr, en, it, es, de, pt, nl, pl). La langue du navigateur est utilisée, `en` par défaut | - |
+| `DEBUG_MODE` | Messages de diagnostic dans la console | `false` |
+
+Plus bas dans le script, `PANORAMAX_SOURCES` liste les serveurs de tuiles (URL et zoom maximum) et`PANORAMAX_LAYER_CONFIG` le nom, la visibilité initiale et le z-index des couches. Le style des points est défini dans la méthode `#setPanoramaxLayerStyle()`.
+
+## Limites connues
 
-Vous pouvez également personnaliser l'apparence du bouton ou le comportement d'affichage selon vos besoins via des
-ajustements dans le fichier JavaScript.
+- En moitié d'écran, les boutons de zoom Lizmap (en haut à droite de la zone carte) sont sous le visualiseur. La carte reste manipulable à la souris.
+- Le mode et la répartition ne sont pas conservés d'une session à l'autre.
 
 # (EN) Panoramax
 
-This script allows you to display photos from the Panoramax project (https://panoramax.openstreetmap.fr/ and/or
-https://panoramax.ign.fr/) in your Lizmap Web Client project. It is not necessary for your project to have a specific
-projection for this script to work. QGIS will handle the reprojection.
+This script displays photos from the Panoramax project (https://panoramax.fr) in Lizmap Web Client, using the IGN (https://panoramax.ign.fr) and OpenStreetMap France (https://panoramax.openstreetmap.fr) instances.
 
-![alt text](image-3.png)
+![Panoramax in Lizmap](image-3.png)
 
-## Requirements
+Two files are provided:
+
+- **`panoramax4_3.9.js`**: **RECOMMENDED VERSION**. Uses the Panoramax V4 web-viewer (Web Components) and creates the Panoramax point layers in the map by itself.
+- **`panoramax3_3.9.legacy.js`**: former version based on the V3 API and on a Panoramax layer added to the QGIS project. Kept for reference, no longer maintained, should not be used, without the display modes described below.
 
-- Lizmap Web Client ≥ 3.8
+## Requirements
 
-- For performance reasons and because OpenLayers does not allow the reprojection of vector tiles, **the Panoramax data
-  layer(s) must be added from your QGIS project**. **A layer or group named Panoramax must exist in your QGIS project.
-  Otherwise, the script will generate an error**. You can change the name of your layer/group, but in that case, you
-  will need to modify the PANORAMAX_QGIS_LAYER_NAME variable in the script to match the name of your layer. You can
-  also modify the vector tiles style in QGIS.
+- Lizmap Web Client 3.9.
+- The browser must reach the jsDelivr CDN (Panoramax web-viewer 4.4.0), the `api.panoramax.xyz` API and the `panoramax.ign.fr` and `panoramax.openstreetmap.fr` tile servers.
+- No Panoramax layer is needed in the QGIS project: the script adds two vector tile layers (IGN and OSM) to the map when the panel is open.
+- No projection constraint: OpenLayers reprojects the tiles on the fly (tested on an EPSG:2975 project).
 
-![alt text](image.png)
-![alt text](image-1.png)
+## Installation
 
+1. Copy `panoramax4_3.9.js` to the `media/js/default` folder of the Lizmap repository (or `media/js/project_name` for a single project).
+2. Reload the map: a button with a camera icon appears in the left bar.
 
 ## Usage
 
-1. copy the panoramax_3.8.js file to the media/js folder of your QGIS project.
-2. verify that the Panoramax layer (or group) exists in your QGIS project.
-3. open Lizmap Web Client and ensure the version installed is 3.8 or higher.
-4. the Panoramax button should now appear in the Lizmap interface, allowing you to view the photos related to the points
-   in the Panoramax layer.
+1. Click the Panoramax button: the minidock opens with the viewer, and the Panoramax points are displayed on the map.
+2. Click a point: the matching photo is displayed. An arrow shows the view azimuth and the map is centred on the photo.
+3. Browse the photos with the viewer arrows or the player under the picture: the map and the arrow follow each photo.
+4. Close the minidock: the Panoramax layers are hidden and the layout goes back to normal.
+
+## Display modes (minidock position)
+
+Two buttons at the top right of the viewer change the page layout:
+
+- **Half screen.** The map area is shared between the map on the left and the photos on the right. A splitter between them can be dragged (map share between 20% and 80%, 50% by default). The map keeps following the photo navigation.
+
+  ![Half screen mode](half-panoramax.jpg)
 
+- **Full map.** The photos take the whole map area and the map becomes a thumbnail at the bottom left, still centred on the current photo. Clicking the thumbnail restores the layout.
+
+  ![Full map mode](full-panoramax.jpg)
+
+A second click on the active button, or closing the minidock, restores the normal layout. Switching directly from one mode to the other works. If a Lizmap panel is open (layers, print, etc.), the map and the photos are placed to its right and follow it when it opens or closes.
+
+Both modes are hidden on the mobile layout and do not exist when `DOCK_POSITION` is `dock`.
 
 ## Customization
 
-If you change the name of the Panoramax group or layer in QGIS, you will need to adjust the `PANORAMAX_QGIS_LAYER_NAME`
-variable in the script to match the name of your layer.
+Constants at the top of the script, above the "DO NOT MODIFY BELOW THIS LINE" marker:
+
+| Constant | Purpose | Default |
+|---|---|---|
+| `DOCK_POSITION` | `minidock` or `dock`. Display modes only exist in `minidock` | `minidock` |
+| `DOCK_ICON`, `DOCK_TITLE` | Button icon and title | `icon-camera`, `Panoramax` |
+| `SPLIT_DEFAULT_PERCENT` | Map share (left side) in half-screen mode | `50` |
+| `SPLIT_MIN_PERCENT`, `SPLIT_MAX_PERCENT` | Splitter bounds | `20`, `80` |
+| `MAP_THUMBNAIL_WIDTH`, `MAP_THUMBNAIL_HEIGHT` | Map thumbnail size in full-map mode (px) | `240`, `160` |
+| `MAP_THUMBNAIL_MARGIN` | Thumbnail distance from the bottom and left edges (px) | `20` |
+| `ARROW_ICON_SIZE`, `ARROW_ICON_COLOR` | Azimuth arrow size and colour | `0.3`, `#e4e8e6` |
+| `PANORAMAX_INSTANCE` | API used by the viewer | `https://api.panoramax.xyz/api` |
+| `CONTENT_TEXT` | Panel and button texts per language (fr, en, it, es, de, pt, nl, pl). The browser language is used, `en` as fallback | - |
+| `DEBUG_MODE` | Diagnostic messages in the console | `false` |
+
+Further down, `PANORAMAX_SOURCES` lists the tile servers (URL and maximum zoom) and `PANORAMAX_LAYER_CONFIG` the name, initial visibility and z-index of the layers. The point style is defined in the `#setPanoramaxLayerStyle()` method.
+
+## Known limits
 
-You can also customize the appearance of the button or the display behavior according to your needs by making
-adjustments to the JavaScript file.
+- In half-screen mode the Lizmap zoom buttons (top right of the map area) sit under the viewer. The map can still be panned and zoomed with the mouse.
+- The mode and the split ratio are not kept between sessions.