173 lines
10 KiB
Markdown
173 lines
10 KiB
Markdown
# Requisits de programari — Visor de trajectòries lagrangianes
|
|
|
|
**Document de requisits · Client**
|
|
|
|
---
|
|
|
|
## Índex
|
|
|
|
1. [Introducció](#1-introducció)
|
|
2. [Descripció general del producte](#2-descripció-general-del-producte)
|
|
3. [Actors i rols](#3-actors-i-rols)
|
|
4. [Requisits funcionals](#4-requisits-funcionals)
|
|
5. [Flux del sistema](#5-flux-del-sistema)
|
|
6. [Entregables](#6-entregables)
|
|
7. [Criteris d'acceptació](#7-criteris-dacceptació)
|
|
8. [Annexos i referències](#8-annexos-i-referències)
|
|
|
|
---
|
|
|
|
## 1. Introducció
|
|
|
|
### 1.1 Objectiu del document
|
|
|
|
Aquest document defineix els requisits de programari del projecte **Visor de trajectòries lagrangianes**. Està dirigit al client i estableix l'abast funcional, els actors, els requisits i els criteris d'acceptació.
|
|
|
|
### 1.2 Abast
|
|
|
|
Inclou el visor web de visualització de trajectòries, l'àrea d'administració per a la càrrega i gestió de dades, el processament de fitxers NetCDF i el desplegament del conjunt. Queden fora d'abast els detalls d'arquitectura i implementació.
|
|
|
|
---
|
|
|
|
## 2. Descripció general del producte
|
|
|
|
- El producte és una **aplicació web** (visor) accessible des del navegador que permet visualitzar partícules contaminants (o similars) en moviment al Mediterrani occidental sobre un mapa.
|
|
- Les partícules tenen origen en punts de la costa catalana, es dispersen amb els corrents durant un període definit (p. ex. 72 h) i, en arribar a la costa, queden encallades i s'acumulen. El visor permet identificar aquestes zones d'impacte de forma visual.
|
|
- El mapa és interactiu (vistes 2D i 3D), amb animació temporal i controls per analitzar les dades. El producte està pensat per a l'anàlisi tècnica i per a la comunicació de resultats (reunions, informes).
|
|
|
|
---
|
|
|
|
## 3. Actors i rols
|
|
|
|
- **Administrador:** usuari amb permisos per pujar fitxers de dades (format NetCDF) i per gestionar les simulacions (consultar llistat, eliminar i, si es pacta, actualitzar o substituir). És l'únic rol amb accés a aquestes operacions.
|
|
- **Usuari final:** usuari que accedeix al visor per consultar simulacions ja publicades. Pot seleccionar simulació, utilitzar el mapa i els controls d'animació, filtres i llegenda. No pot pujar ni eliminar dades.
|
|
|
|
---
|
|
|
|
## 4. Requisits funcionals
|
|
|
|
### 4.1 Administració i càrrega de dades
|
|
|
|
- **REQ-F-01** El sistema ha de permetre a l'administrador pujar fitxers NetCDF des d'una àrea d'administració dedicada.
|
|
- **REQ-F-02** Els fitxers NetCDF hauran d'ajustar-se al format acordat (variables de longitud, latitud, velocitats, estat d'encallament, eixos de temps i partícules).
|
|
- **REQ-F-03** El sistema ha de mostrar a l'administrador un llistat de simulacions disponibles (identificador, nom o data, segons implementació).
|
|
- **REQ-F-04** El sistema ha de permetre a l'administrador eliminar simulacions. La simulació eliminada deixa d'estar disponible per als usuaris finals.
|
|
- **REQ-F-05** Si es pacta, el sistema ha de permetre actualitzar o substituir fitxers existents sense crear una simulació nova.
|
|
- **REQ-F-06** Un cop pujat un fitxer NetCDF, el sistema ha de validar-lo, processar-lo i deixar les dades disponibles per al visor sense intervenció manual addicional de l'administrador.
|
|
|
|
### 4.2 Visor — Mapa i visualització
|
|
|
|
- **REQ-F-07** El visor ha de mostrar un mapa base interactiu sobre el qual es dibuixen les trajectòries, amb zoom i desplaçament (pan).
|
|
- **REQ-F-08** El visor ha de oferir diversos estils de mapa base (p. ex. clar, fosc) seleccionables per l'usuari.
|
|
- **REQ-F-09** El visor ha de suportar visualització en 2D i 3D de les trajectòries.
|
|
- **REQ-F-10** El visor ha de mostrar l'estela del moviment de cada partícula (traça temporal) per diferenciar les partícules en moviment de les encallades.
|
|
- **REQ-F-11** El visor ha d'assignar un color per punt d'origen (llançament) per permetre identificar l'origen de cada partícula.
|
|
- **REQ-F-12** El visor ha de diferenciar visualment les partícules actives (en moviment) de les encallades (p. ex. mitjançant color o símbol).
|
|
|
|
### 4.3 Visor — Animació i temps
|
|
|
|
- **REQ-F-13** El visor ha d'oferir controls de reproducció: iniciar (play) i aturar (pausa) l'animació temporal.
|
|
- **REQ-F-14** El visor ha d'oferir un control de velocitat de l'animació (múltiples graus, des de més lent fins a més ràpid).
|
|
- **REQ-F-15** El visor ha d'oferir un control (slider o equivalent) per desplaçar-se directament a un instant temporal concret sense reproduir l'animació completa.
|
|
- **REQ-F-16** El visor ha de mostrar l'instant temporal actual (p. ex. "Dia 2 · 14:00" o data real si les dades la inclouen).
|
|
|
|
### 4.4 Visor — Filtres i capes
|
|
|
|
- **REQ-F-17** El visor ha d'oferir un panell o menú de filtres per activar o desactivar capes visuals: esteles de moviment, partícules actives i partícules encallades.
|
|
- **REQ-F-18** El visor ha de permetre canviar l'estil del mapa base des del panell de filtres o un menú equivalent.
|
|
|
|
### 4.5 Visor — Informació i ajuda
|
|
|
|
- **REQ-F-19** El visor ha de mostrar informació addicional (tooltip) en passar el cursor sobre una partícula: com a mínim origen i velocitat en aquell instant.
|
|
- **REQ-F-20** El visor ha d'incloure una llegenda que expliqui el significat dels colors, orígens i estats (actiu / encallat) per a la interpretació per part de qualsevol usuari.
|
|
|
|
### 4.6 Visor — Navegació i simulacions
|
|
|
|
- **REQ-F-21** El visor ha d'oferir una acció (p. ex. botó) per encuadrar totes les partícules visibles al mapa mitjançant zoom automàtic.
|
|
- **REQ-F-22** Quan existeixin diverses simulacions, el visor ha de permetre seleccionar quina simulació visualitzar (desplegable, selector o paràmetre d'URL) i carregar les dades corresponents.
|
|
|
|
---
|
|
|
|
## 5. Flux del sistema
|
|
|
|
### 5.1 Flux de dades
|
|
|
|
L'administrador puja fitxers NetCDF. El sistema els valida, els processa (incloent submostreig horari quan sigui aplicable) i genera les dades i metadades necessàries per al visor. Les simulacions queden disponibles per a tots els usuaris amb accés al visor. L'usuari final obre el visor, selecciona una simulació i utilitza els controls d'animació, filtres, tooltips i llegenda.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Administrador<br/>puja NetCDF] --> B[Sistema<br/>valida i processa]
|
|
B --> C[Simulacions<br/>disponibles]
|
|
C --> D[Usuari<br/>visualitza al visor]
|
|
```
|
|
|
|
*Figura 1 — Flux de dades.*
|
|
|
|
### 5.2 Flux d'ús del visor
|
|
|
|
L'usuari accedeix al visor des del navegador, selecciona simulació (o se n'ofereix una per defecte), el mapa es carrega amb les trajectòries i l'usuari pot utilitzar zoom, desplaçament, controls de reproducció, filtres, tooltips i zoom a partícules.
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
O([Obrir visor]) --> T[Triar simulació]
|
|
T --> M[Mapa amb trajectòries]
|
|
M --> C{Controls}
|
|
C --> P[Play / Pausa / Velocitat]
|
|
C --> S[Slider temporal]
|
|
C --> F[Filtres i capes]
|
|
C --> Z[Zoom a partícules]
|
|
C --> L[Tooltips i llegenda]
|
|
```
|
|
|
|
*Figura 2 — Flux d'ús del visor.*
|
|
|
|
---
|
|
|
|
## 6. Entregables
|
|
|
|
- **Visor web:** aplicació accessible des del navegador que implementa els requisits de les seccions 4.2 a 4.6 (mapa, animació, controls de temps, filtres, tooltips, llegenda).
|
|
- **Àrea d'administració:** interfície que implementa els requisits REQ-F-01 a REQ-F-06 (pujada de NetCDF, llistat, eliminació i, si s'acorda, actualització o substitució).
|
|
- **Processament de dades:** pipeline de validació i transformació dels fitxers NetCDF pujats per deixar les dades disponibles per al visor sense accions manuals addicionals.
|
|
- **Documentació d'ús:** instruccions per a l'administrador (càrrega i gestió de fitxers) i per a l'usuari final (ús del visor i controls), segons pacte.
|
|
- **Desplegament:** conjunt (visor, administració i processament) desplegat de forma reproducible (p. ex. contenidors), segons acord, per a la posada en marxa en l'entorn del client.
|
|
|
|
---
|
|
|
|
## 7. Criteris d'acceptació
|
|
|
|
El projecte es donarà per acceptat quan es compleixin les condicions següents:
|
|
|
|
- L'administrador pot pujar fitxers NetCDF en el format acordat i pot llistar i eliminar simulacions des de la interfície d'administració.
|
|
- El visor mostra les trajectòries amb animació temporal i diferenciació clara entre partícules en moviment i encallades, i entre orígens (mitjançant colors i llegenda).
|
|
- L'usuari final pot utilitzar sense errors els controls de reproducció (play, pausa, velocitat, slider), el panell de filtres i capes, els tooltips i la llegenda, la selecció de simulació i el zoom a partícules.
|
|
- El rendiment del visor és acceptable amb el volum de partícules i passos temporals definits al projecte (reproducció fluida sense bloquejos evidents).
|
|
|
|
---
|
|
|
|
## 8. Annexos i referències
|
|
|
|
Referències externes per contextualitzar el tipus de visualització. Les captures recomanades poden emprar-se per a documentació o presentacions del client.
|
|
|
|
### 8.1 Enllaços de referència
|
|
|
|
- [deck.gl](https://deck.gl) — motor de visualització del visor.
|
|
- [Trips Layer](https://deck.gl/examples/trips-layer) — exemple de trajectòries animades amb estela; referència propera al comportament del visor.
|
|
- [Exemples deck.gl](https://deck.gl/examples).
|
|
- [MapLibre](https://maplibre.org) — mapes base (sense clau d'API). [Demos](https://maplibre.org/demos/).
|
|
- [Apache Arrow](https://arrow.apache.org) — format intern de dades (informatiu).
|
|
|
|
### 8.2 Captures recomanades per a documentació o presentació
|
|
|
|
- **Captura principal:** [deck.gl — Trips Layer](https://deck.gl/examples/trips-layer). Obrir l'enllaç, activar l'animació (Play) i realitzar una captura de pantalla amb trajectòries amb estela i colors. Representa de forma adequada el tipus de visualització del producte.
|
|
- **Captura opcional:** [MapLibre — Demos](https://maplibre.org/demos/). Seleccionar un estil de mapa (clar o fosc) i realitzar una captura per il·lustrar l'aspecte del mapa base del visor.
|
|
|
|
---
|
|
|
|
*Document de requisits de programari. Per a consultes sobre requisits o abast, contactar amb el proveïdor.*
|
|
|
|
---
|
|
|
|
### Ús del document en Word
|
|
|
|
Seleccioneu tot el contingut (Ctrl+A), copieu i enganxeu en un document Word. Per incloure els diagrames, obrir el fitxer HTML al navegador, realitzar una captura de pantalla de cada diagrama (p. ex. Win+Shift+S) i enganxar-les al document. Per il·lustrar el visor, afegir la captura de [Trips Layer](https://deck.gl/examples/trips-layer) amb l'animació activa (secció 8.2).
|