Requisits de programari — Visor de trajectòries lagrangianes

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.

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.

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ó