# Requisits de programari — Visor de trajectòries lagrangianes

Document de requisits · Client

## 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 de 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 de oferir controls de reproducció: iniciar (play) i aturar (pausa) l’animació temporal.
- REQ-F-14 El visor ha de 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 de 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 de 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

Informació contextual en passar el cursor sobre elements del mapa i llegenda per interpretar colors i estats.

- REQ-F-19 Tooltip sobre partícula: com a mínim origen i velocitat en aquell instant.
- REQ-F-20 Llegenda amb el significat dels colors, orígens i estats (actiu / encallat).

### 4.6 Visor — Navegació i simulacions

- REQ-F-21 El visor ha de 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.

flowchart LR A[Administrador
puja NetCDF] --> B[Sistema
valida i processa] B --> C[Simulacions
disponibles] C --> D[Usuari
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.

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 — motor de visualització del visor.
- Trips Layer — exemple de trajectòries animades amb estela; referència propera al comportament del visor.
- Exemples deck.gl.
- MapLibre — mapes base (sense clau d’API). Demos.
- Apache Arrow — format intern de dades (informatiu).

### 8.2 Captures recomanades per a documentació o presentació

- Captura principal: deck.gl — 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. 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 aquest fitxer 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 amb l’animació activa (secció 8.2).