Questo plugin per QGIS porta Segment Anything Model 2 (SAM2) di Meta dentro a QGIS permettendo di fare instance segmentation direttamente sul tuo PC e completamente offline. Nessuna API cloud, nessuna GPU dedicata — i modelli girano in locale tramite ONNX Runtime.

Il plugin fa parte dell'ecosistema SamGIS. Mentre la demo web si basa su un backend FastAPI usando dei tile provider remoti (es. OpenStreetMap) SamGIS per QGIS funziona interamente offline con qualsiasi immagine georeferenziata presente in un progetto QGIS.

I modelli vengono scaricati una sola volta da Hugging Face e salvati in locale in ~/.samgis/models/.

Screenshots

Come funziona

1. Installare il plugin QGIS =) (le dipendenze Python vengono gestite "sotto al cofano" dal plugin stesso)
2. Caricare un layer raster georeferenziato in QGIS
3. Creare layer vettoriali con prompt a punti singoli (foreground/background) o rettangoli (solo foreground)
4. Selezionare dalla finestra modale SamGIS il layer raster ed il (oppure i) layer vettoriali prescelti
5. Nel caso non sia presente neppure un modello SAM2 il plugin proporrà la scelta del modello di cui fare download (es. "SAM 2.1 Tiny uint8" ~32 MB per iniziare rapidamente)
6. Il processo a questo punto
   1. converte le coordinate geografiche (o proiettate, a seconda del CRS) in coordinate pixel
   2. esegue la fase di riconoscimento vero e proprio usando il modello selezionato
   3. restituisce la maschera di segmentazione convertita in un layer vettoriale poligonale avente come CRS "EPSG:4326"

Funzionalità principali

• Completamente offline — i modelli vengono scaricati una sola volta e salvati in locale
• 8 varianti di modello — 4 dimensioni (Tiny, Small, Base+, Large) x 2 precisioni (uint8, fp32)
• Prompt a punti — punti foreground (label=1) e background (label=0)
• Prompt a rettangolo — bounding box tramite layer vettoriale poligonale
• Inferenza in background — l'interfaccia resta reattiva durante l'esecuzione del modello
• Gestione multi-banda — supporta raster in scala di grigi, RGB e multi-banda (1-3 bande)
• Output EPSG:4326 — i risultati vengono aggiunti come layer vettoriali poligonali
• Gestione dei modelli — download e selezione tramite una modale dedicata alla configurazione

Risorse

• Codice sorgente e documentazione completa: trincadev/samgis-qgis-plugin
• Correlati: demo web SamGIS
• Richiede QGIS 3.40+ LTR

This QGIS plugin brings Meta's Segment Anything Model 2 (SAM2) into QGIS, enabling instance segmentation directly on your PC and fully offline. No cloud APIs, no dedicated GPU — models run on-device via ONNX Runtime.

The plugin is part of the SamGIS ecosystem. While the web demo relies on a FastAPI backend using remote tile providers (e.g. OpenStreetMap), SamGIS for QGIS works entirely offline with any georeferenced image in a QGIS project.

Models are downloaded once from Hugging Face and stored locally in ~/.samgis/models/.

Screenshots

How it works

1. Install the QGIS plugin =) (the Python dependencies are handled under the hood by the plugin itself)
2. Load a georeferenced raster layer in QGIS
3. Create vector layers with point prompts (foreground/background) or rectangles (foreground only)
4. Select the raster layer and the vector layer(s) from the SamGIS modal dialog
5. If no SAM2 model is present, the plugin will prompt you to choose and download one (e.g. "SAM 2.1 Tiny uint8" ~32 MB for a quick start)
6. The pipeline then
   1. converts geographic (or projected, depending on the CRS) coordinates to pixel coordinates
   2. runs the actual inference using the selected model
   3. returns the segmentation mask converted to a polygon vector layer with CRS "EPSG:4326"

Key features

• Fully offline — models are downloaded once and stored locally
• 8 model variants — 4 sizes (Tiny, Small, Base+, Large) x 2 precisions (uint8, fp32)
• Point prompts — foreground (label=1) and background (label=0) points
• Rectangle prompts — bounding box via polygon vector layer
• Background inference — UI stays responsive during model execution
• Multi-band handling — supports grayscale, RGB, and multi-band rasters (1-3 bands)
• EPSG:4326 output — results are added as polygon vector layers
• Model management — download and selection via a dedicated settings dialog

Resources

• Source code and full documentation: trincadev/samgis-qgis-plugin
• Related: SamGIS web demo
• Requires QGIS 3.40+ LTR

Una camminata a Santa Caterina Valfurva

Ventinove vedute di Santa Caterina Valfurva e dintorni

Foto scattate il 8 December 2025.

A walk around Santa Caterina Valfurva

Twenty-nine views of Santa Caterina Valfurva and surroundings

Photos taken on 8 December 2025.

Tempo fa ho iniziato a scrivere la bozza di un testo. Un po' per curiosità professionale, un po' per semplice noia, ho deciso di pensare a quale tipo di applicazione dell'intelligenza artificiale fosse fattibile, a parte l'ovvi generazione di testo tramite un prompt ad un LLM.

In particolare ho notato specialmente i LLM (Large Language Models) "piccoli" abbiano la tendenza a ripetersi ed a inserire parole duplicate. Per questo motivo ho cercato un progetto open source che potessi eseguire sul mio pc e tramite cui individuare parole duplicate: non ho trovato niente di utile o che comunque facesse quel che volevo io.

Questo ha portato alla creazione di My Ghost Writer, un progetto open source che sta ora sto integrando in lite.koboldai.net — un'interfaccia web scritta in JS ed HTML senza dipendenze per KoboldCpp.

lite.koboldai.net

lite.koboldai.net è un'interfaccia web senza dipendenze progettata per l'uso come backend per modelli linguistici di grandi dimensioni (LLM) come KoboldCpp. Funziona interamente nel browser (non richiede installazione) ed è confezionata come un singolo file HTML statico:

• Modalità multiple: Modalità Storia, Modalità Chat, Modalità Istruttoria e Modalità Avventura per diversi tipi di interazione con l'IA.
• Ampia compatibilità: Funziona con KoboldAI Client, KoboldCpp e AI Horde; supporta sia modelli locali che remoti.
• Strumenti creativi: Include un editor di testo, la generazione di immagini tramite Stable Diffusion e il supporto per le schede dei personaggi e gli scenari.
• Facile da usare: Facile da usare, stili dell'interfaccia utente personalizzabili e funzioni come il salvataggio automatico, il text-to-speech e le opzioni di ripetizione/modifica.

È una buona opzione se si desidera un'interfaccia leggera e flessibile per la narrazione, il gioco di ruolo o la scrittura assistita dall'intelligenza artificiale. La struttura del codice è un po' disordinata:

• Index.html monolitico con oltre 26000 righe di codice js, css e html.
• Solo JS, nessun dattiloscritto ovviamente.
• Il codice JS incorporato di terze parti è obsoleto.
• Mancano test E2E.

Il Problema con WordSearch in lite.koboldai.net

WordSearch (basata sulla mia prima implementazione) in lite.koboldai.net fa semplicemente una ricerca testuale per rilevare duplicati avendo però limitazioni significative:

• Identifica anche parti di testo non rilevanti (es. la singola lettera "a", anche dove presente dentro ad altre parole).
• Non distingue tra parole semanticamente diverse (es. "the" e "they").

La Soluzione: Stemming NLP con My Ghost Writer

Per risolvere questo problema, ho reimplementato la logica di rilevazione dei duplicati utilizzando lo stemming NLP (tramite l'algoritmo Porter Stemming, già incluso dentro a lite.koboldai.net), che riduce le parole alla loro forma radice (es. "running" → "run"). Questo approccio:

• Raggruppa parole semanticamente correlate (es. "run", "running", "ran").
• Riduce i falsi positivi concentrandosi su veri duplicati.
• Supporta sia l'input manuale che l'upload di file per flessibilità.

Funzionalità Attuali e Limitazioni

Funzionalità Principali

• Ricerca delle parole duplicate, tramite stemming.
• Thesaurus (work in progress):
  • Alimentato da chiamate ad WordsAPI.
  • Persistenza dei dati opzionale con un database MongoDB locale.
  • Limitato a termini comuni ⚠️, non supporta (per ora) nomi propri o espressioni con parole multiple.

Tecnologie Utilizzate

• Backend:
  • Python 3.10+ con FastAPI per eseguire l'applicazione web.
  • Structlog per il logging e la gestione degli errori.
  • Poetry per la gestione delle dipendenze.
  • Docker per la containerizzazione.
• Frontend:
  • JavaScript vanilla (nessun framework a causa dell'integrazione con lite.koboldai.net).
  • Playwright per i test end-to-end (E2E).

Risorse

• Repository GitHub di My Ghost Writer
• lite.koboldai.net
• WordsAPI

Some time ago I started drafting a text. Out of professional curiosity and sheer boredom, I wondered what kind of AI applications were feasible beyond the obvious text generation via prompts to LLMs.

In particular, I noticed that smaller LLM (Large Language Models) tend to repeat themselves and insert duplicate words. This led me to search for an open-source project I could run on my PC to identify duplicate words – but I found nothing useful or that did exactly what I wanted.

This ultimately led to the creation of My Ghost Writer, an open-source project now being integrated into lite.koboldai.net – a lightweight, dependency-free web interface for KoboldCpp.

lite.koboldai.net

lite.koboldai.net is a dependency-free web interface designed as a backend for large language models (LLM) like KoboldCpp. It runs entirely in the browser (no installation required) and is packaged as a single static HTML file:

• Multiple modes: Story mode, Chat mode, Instruction mode, and Adventure mode for different types of AI interaction.
• Broad compatibility: Works with KoboldAI Client, KoboldCpp, and AI Horde; supports both local and remote models.
• Creative tools: Includes a text editor, image generation via Stable Diffusion, and support for character sheets and scenarios.
• User-friendly: Easy to use, customizable UI styles, and features like auto-save, text-to-speech, and repeat/edit options.

It's a great option if you want a lightweight, flexible interface for storytelling, role-playing, or AI-assisted writing. However, the code structure is somewhat messy:

• A monolithic index.html with over 26,000 lines of JS, CSS, and HTML.
• Only vanilla JS, no TypeScript obviously.
• Outdated third-party JS code.
• Missing E2E tests.

The Problem with WordSearch in lite.koboldai.net

The initial version of WordSearch (based on my first implementation) in lite.koboldai.net used simple text search to detect duplicates, but had significant limitations:

• Identified irrelevant text fragments (e.g., the single letter "a" even when embedded in other words).
• Couldn't distinguish between semantically different words (e.g., "the" vs. "they").

The Solution: NLP Stemming with My Ghost Writer

To solve this, I reimplemented the duplicate detection logic using NLP stemming (via the Porter Stemming algorithm, already included in lite.koboldai.net), which reduces words to their root form (e.g., "running" → "run"). This approach:

• Groups semantically related words (e.g., "run", "running", "ran").
• Reduces false positives by focusing on real duplicates.
• Supports both manual input and file upload for flexibility.

Current Features and Limitations

Main Features

• Duplicate word detection via stemming.
• Thesaurus (work in progress):
  • Powered by calls to WordsAPI.
  • Optional data persistence with a local MongoDB database.
  • Limited to common terms ⚠️, doesn't support (for now) proper nouns or multi-word expressions.

Technologies Used

• Backend:
  • Python 3.10+ with FastAPI to run the webapp.
  • Structlog for logging and error handling.
  • Poetry for dependency management.
  • Docker for containerization.
• Frontend:
  • Vanilla JavaScript (no framework due to integration with lite.koboldai.net).
  • Playwright for end-to-end (E2E) testing.

Resources

• GitHub Repository for My Ghost Writer
• lite.koboldai.net
• WordsAPI

Right now (April 2025) Microsoft permits to configure WSL2 in mirrored networking (and DNS Tunnelling) mode:

[wsl2]
networkingMode=mirrored
dnsTunneling=true

That's useful for access a webserver you run within your WSL2 instance in localhost from the host machine. E.g. a simple python webserver executed like this from the command line:

python -m http.webserver

it's accesible from a browser on the host machine at the address http://localhost:8000/.

But... What if you you are developing a webserver within your WSL2 instance and you needs to test this webserver within a VirtualBox VM?

A simple solution is:

1. check for the existance of a dedicated Host-Only Ethernet Adapter created by VirtualBox; its DHCP Server will use a IP/netmask and DNS configuration like this:

   IPv4 Address	192.168.99.1
   IPv4 Network Mask	255.255.255.0

   Server Address	192.168.99.50
   Server Mask	255.255.255.0
   Lower Address Bound	192.168.99.99
   Upper Address Bound	192.168.99.254

2. Install the Hyper-V Service, command line tool and GUI tools. Then following this guide we can create an external switch that use our existing VirtualBox Host-Only Ethernet Adapter.

3. that's the result with ipconfig from a powershell session:

   cmd

   Ethernet adapter vEthernet (hyperv-to-virtualkbox):
   
   Connection-specific DNS Suffix  . :
   Link-local IPv6 Address . . . . . : fe80::aa:bb:cc:aaf%28
   IPv4 Address. . . . . . . . . . . : 192.168.99.1
   Subnet Mask . . . . . . . . . . . : 255.255.255.0
   Default Gateway . . . . . . . . . :

4. In the end it's possible the connect from the WSL2 instance to the VirtualBox VM like this:

   bash

   ssh user@192.168.99.51

Where 192.168.99.51 is the VM ip. See also this article about ssh forwarding.

In questo momento (aprile 2025) Microsoft permette di configurare WSL2 in modalità mirrored networking (e DNS Tunnelling):

[wsl2]
networkingMode=mirrored
dnsTunneling=true

Questo è utile per esporre un webserver eseguito all'interno della propria istanza WSL2 in localhost direttamente da un browser sulla macchina host. Ad esempio un semplice webserver python eseguito in questo modo dalla linea di comando:

python -m http.webserver

è accessibile da un browser sulla macchina host all'indirizzo http://localhost:8000/.

Ma... Come fare nel caso si stia sviluppando un webserver all'interno della propria istanza WSL2 e si abbia bisogno di testare questo webserver all'interno di una macchina virtuale VirtualBox?

Una soluzione semplice è:

1. verificare l'esistenza di un Host-Only Ethernet Adapter presente in VirtualBox; questo avrà configurazione IP/netmask e server DHCP fatto così:

   IPv4 Address	192.168.99.1
   IPv4 Network Mask	255.255.255.0

   Server Address	192.168.99.50
   Server Mask	255.255.255.0
   Lower Address Bound	192.168.99.99
   Upper Address Bound	192.168.99.254

2. Installare il servizio Hyper-V, il relativo strumento a riga di comando e della GUI. Usando poi questa guida creiamo uno switch esterno basato sul dispositivo di rete Host-Only VirtualBox.

3. Ecco il risultato con ipconfig da una sessione powershell:

   cmd

   Adattatore Ethernet vEthernet (hyperv-to-virtualkbox):
   
   Suffisso DNS specifico della connessione . :
   Indirizzo IPv6 Link-local . . . . : fe80::aa:bb:cc:aaf%28
   Indirizzo IPv4. . . . . . . . . . . : 192.168.99.1
   Maschera di sottorete . . . . . . . . . . . : 255.255.255.0
   Gateway predefinito. . . . . . . . . . . :

4. Alla fine è possibile connettersi dall'istanza WSL2 alla VM VirtualBox in questo modo:

   bash

   ssh user@192.168.99.51

Dove 192.168.99.51 è l'ip della VM. Si veda anche questo articolo con cui fare port forwarding ssh.

Local Forwarding

Local forwarding is used to forward a specific port on the local machine to a specific port on the remote server. This can be useful when a service on the remote server is accessible from the local machine only through a Bastion Host because of a firewall:

ssh -L local-port:remote-private-service.example.com:remote-private-port bastion-host-user@bastion-host.example.com

For example, to access via local port 8080 to the remote port service 80 you can use the command:

ssh -L 8080:remote-private-service.example.com:80 bastion-host-user@bastion-host.example.com

Remote Forwarding

Remote forwarding is used to forward a specific port on the remote server to a specific port on the local machine. This can be useful when a service on the local machine is not accessible from the remote server due to a firewall. The command to use:

ssh -L remote-private-port:local-server:local-port user@remote-host.example.com

For example, remote users could access a service running on a local server this way:

ssh -R 80:localhost:8080 user@remote-host.example.com

Some more useful SSH options

• -f Requests ssh to go to background just before command execution. This is useful if ssh is going to ask for passwords or passphrases, but the user wants it in the background.
  This implies -n. [...] If the ExitOnForwardFailure configuration option is set to "yes", then a client started with -f will wait for all remote port forwards to be successfully established before placing itself in the background. Refer to the description of ForkAfterAuthentication in ssh_config(5) for details.

• -N Do not execute a remote command. This is useful for just forwarding ports. Refer to the description of SessionType in ssh_config(5) for details.

Local Forwarding

Il "forward locale" è utilizzato per fare forward di una data porta esistente in locale ad una data porta esistente su un server remoto. Ciò può essere utile quando un servizio sul server remoto è accessibile dal computer locale solo attraverso un Bastion Host a causa di un firewall:

ssh -L local-port:remote-private-service.example.com:remote-private-port bastion-host-user@bastion-host.example.com

Esempio, per accedere tramite la porta locale 8080 al servizio remoto esposto alla porta 80 si può utilizzare la seguente comando:

ssh -L 8080:remote-private-service.example.com:80 bastion-host-user@bastion-host.example.com

Remote Forwarding

Il "forward remoto" è utilizzato per fare il forward di una data porta presente sul server remoto ad una data porta presente su una macchina locale. Ciò può essere utile quando un servizio presente su una macchina locale non è accessibile dal server remoto a causa di un firewall. La riga di comando da usare:

ssh -L remote-private-port:local-server:local-port user@remote-host.example.com

Ad esempio, degli utenti remoti possono accedere al servizio in esecuzione sul server locale in questo modo:

ssh -R 80:localhost:8080 user@remote-host.example.com

Alcune opzioni SSH utili

• L'opzione -f configura ssh ad andare in background appena prima dell'esecuzione del comando. Ciò è utile se ssh dovrà ricevere password, ma l'utente ne richiede l'esecuzione in background. Questo implica -n. [...] Se la configurazione ExitOnForwardFailure è impostata a "yes", allora un client eseguito con -f attende che tutte le connessioni alle porte remote siano stabilite prima di andare in background. Si faccia riferimento alla descrizione della funzione ForkAfterAuthentication in ssh_config(5) per ulteriori dettagli.

• -N Non eseguire un comando remoto. Ciò è utile per eseguire solo il forwarding di porte. Si riferisce alla descrizione di SessionType in ssh_config(5) per ulteriori dettagli.

In this article, I present the project I am working on: AI Pronunciation Trainer (online here), a tool designed to help you improve your pronunciation using the power of artificial intelligence. This project is a refactor of the original AI Pronunciation Trainer by Thiagohgl to which I have made several improvements to make the tool more effective and easier to use.

What it is and what it does

AI Pronunciation Trainer is a tool that uses AI to evaluate your pronunciation and provide feedback, helping you to improve and be understood more clearly. It leverages the Silero STT / TTS, openai whisper and faster whisper models for speech-to-text functionalities (Silero does also text-to-speech), ensuring accurate and reliable pronunciation assessment.

Refactor: upgraded frontend and backend libraries

About the backend:

• Updated PyTorch at version 2.6.x
• Updated Silero German Speech-to-Text model to resolve a bug that prevented the use of PyTorch versions later than 1.13.x
• Improved backend tests with the mutation test suite Cosmic Ray
• Fixed a bug with whisper not properly transcribing the end timestamp for the last word in the recorded audio (in the end I solved it switching to the openai whisper python pip package)
• Added faster whisper model support:
  • it avoids None values on end_ts timestamps for the last elements, unlike the HuggingFace Whisper's output
  • it uses silero-vad to detect long silences within the audio

Furthermore, regarding the frontend:

• Updated the JavaScript libraries using the latest versions of jQuery (3.7.1) and Bootstrap (5.3.3)
• New frontend based on Gradio 5.x
• Added E2E tests with Playwright
• Added the ability to insert custom sentences to read and evaluate
• Onboarding tour for new users made with driver.js and custom css/javascript in Gradio blocks
• Playback of individual words in the recording followed by the 'ideal' pronunciation of the same word read by the Text-to-Speech engine
• Also added an in-browser Text-to-Speech functionality (on Windows 11, it only works if the English and German language packs are installed)
• Custom webApp frontend - improved CSS style on mobile devices

Online version: the HuggingFace Space Demo

You can try it online using the HuggingFace Space. This online demo allows you to experience the tool's capabilities without any installation or configuration. The HuggingFace Space provides a convenient and accessible way to test the AI Pronunciation Trainer and see how it can help you improve your pronunciation. Please be patient, sometimes it is a bit slow or in sleeping mode (locally it is much faster, especially if you have a powerful computer). Here is an embedded version of my HuggingFace Space:

Future Work

Although this tool works pretty good, there are still some areas for improvement. Here are some of the future enhancements I plan to implement:

• Receive feedback from the original project author (Thiago Lobato) on my documentation and changes
• Ask the original author for explanations on the architectural and functional choices he made
• Explore transitioning PyTorch to onnxruntime (if possible)
• Re-add the docker container (if possible)

Conclusion

AI Pronunciation Trainer is a valuable tool for anyone looking to improve their pronunciation. With the power of AI and the improvements made in the refactoring project, this tool provides accurate and reliable feedback to help you speak more clearly and confidently. I invite you to try the HuggingFace Space demo and understand how this little project can help you on your journey to better pronunciation.

In questo articolo presento progetto a cui sto lavorando attualmente: AI Pronunciation Trainer (online qui), uno strumento progettato per aiutarvi a migliorare la vostra pronuncia utilizzando la potenza dell'intelligenza artificiale. Questo progetto è un refactor dell'originale AI Pronunciation Trainer di Thiagohgl a cui ho fatto diversi miglioramenti per rendere lo strumento più efficace e facile da usare.

Cos'è e cosa fa

AI Pronunciation Trainer è uno strumento che utilizza l'intelligenza artificiale per valutare la vostra pronuncia e fornire feedback, aiutandovi a migliorare e a essere compresi più chiaramente. Utilizza i modelli Silero STT / TTS, openai whisper e faster whisper per le funzionalità di speech-to-text (Silero permette anche di fare text-to-speech), garantendo una valutazione della pronuncia accurata e affidabile.

Refactor: aggiornamento delle Librerie Frontend e Backend

A proposito del backend:

• PyTorch è adesso alla versione 2.6.x
• aggiornato il modello Silero tedesco di Speech-to-Text per risolvere un bug che impediva l'utilizzo di PyTorch successivo alla versione 1.13.x.
• Migliorati i test di backend python usando la mutation test suite Cosmic Ray
• Risolto un bug per cui whisper non leggeva correttamente il timestamp finale for l'ultima parola nella registrazione (alla fine ho risolto usando il pacchetto pip openai whisper)
• Aggiunto supporto per il pacchetto pip faster whisper:
  • evita i valori None sui end_ts timestamp nell'ultima parola della registrazione al contrario dell'output dell'output di whisper creato con la pipeline HuggingFace
  • permette di individuare momenti di silenzio prolungato tramite silero-vad

Inoltre, per quanto riguarda il frontend:

• Aggiornate le librerie javascript utilizzando le versioni più recenti di jQuery (3.7.1) e Bootstrap (5.3.3)
• Nuovo frontend basato su Gradio 5.x
• Aggiunti test E2E con Playwright
• Aggiunta la possibilità di scrivere, leggere ed ovviamente valutare una frase a scelta libera
• Tour guidato per i nuovi utenti con driver.js ed css/javascript custom dentro ai Gradio blocks
• Riproduzione delle singole parole nella registrazione seguite dalla pronuncia 'ideale' della stessa parola letta dal motore Text-to-Speech
• Aggiunto anche una funzionalità di Text-to-Speech in-browser (su Windows 11 funziona solo nel caso siano installati i pacchetti linguistici inglesi e tedesco)
• Frontend custom webApp - migliorato lo stile CSS su dispositivi mobile

Versione online: la demo su HuggingFace

Potete provare online il mio progetto sul mio HuggingFace Space. Questa demo online vi permette di sperimentare le capacità dello strumento senza alcuna installazione o configurazione. Lo spazio HuggingFace fornisce un modo conveniente e accessibile per testare AI Pronunciation Trainer e vedere come può aiutarvi a migliorare la vostra pronuncia. Si prega di essere pazienti, a volte è un po' lento oppure in sleeping nel caso non sia utilizzato da nessuno da un po' (localmente è molto più veloce, soprattutto se avete un computer potente). Ecco una versione embedded dello spazio HuggingFace:

Sviluppi Futuri

Pur funzionando piuttosto bene, ci sono ovviamente margini di miglioramento. Ecco alcuni dei miglioramenti futuri che intendo implementare:

• Ricevere feedback dall'autore del progetto originale (Thiago Lobato) sulla mia documentazione e sulle modifiche
• Chiedere all'autore del lavoro originale alcune spiegazioni sulle scelte architetturali e funzionali che ha fatto
• Valutare il passaggio da PyTorch a onnxruntime (se possibile)
• Aggiungere nuovamente il container docker (se possibile)

Conclusione

AI Pronunciation Trainer è uno strumento utile per chiunque desideri migliorare in autonomia la propria pronuncia. Con la potenza dell'IA ed i miglioramenti apportati durante il refactor, questo strumento fornisce feedback accurati e affidabili per aiutarvi a parlare in modo più chiaro e sicuro. Vi invito a provare la demo HuggingFace Space e capire come questo progetto possa aiutarvi nel vostro percorso verso una migliore pronuncia.

In questo articolo presento progetto a cui sto lavorando attualmente: AI Pronunciation Trainer (online qui), uno strumento progettato per aiutarvi a migliorare la vostra pronuncia utilizzando la potenza dell'intelligenza artificiale. Questo progetto è un refactor dell'originale AI Pronunciation Trainer di Thiagohgl a cui ho fatto diversi miglioramenti per rendere lo strumento più efficace e facile da usare.

Cos'è e cosa fa

AI Pronunciation Trainer è uno strumento che utilizza l'intelligenza artificiale per valutare la vostra pronuncia e fornire feedback, aiutandovi a migliorare e a essere compresi più chiaramente. Utilizza i modelli Silero STT / TTS, openai whisper e faster whisper per le funzionalità di speech-to-text (Silero permette anche di fare text-to-speech), garantendo una valutazione della pronuncia accurata e affidabile.

Refactor: aggiornamento delle Librerie Frontend e Backend

A proposito del backend:

• PyTorch è adesso alla versione 2.6.x
• aggiornato il modello Silero tedesco di Speech-to-Text per risolvere un bug che impediva l'utilizzo di PyTorch successivo alla versione 1.13.x.
• Migliorati i test di backend python usando la mutation test suite Cosmic Ray
• Risolto un bug per cui whisper non leggeva correttamente il timestamp finale for l'ultima parola nella registrazione (alla fine ho risolto usando il pacchetto pip openai whisper)
• Aggiunto supporto per il pacchetto pip faster whisper:
  • evita i valori None sui end_ts timestamp nell'ultima parola della registrazione al contrario dell'output dell'output di whisper creato con la pipeline HuggingFace
  • permette di individuare momenti di silenzio prolungato tramite silero-vad

Inoltre, per quanto riguarda il frontend:

• Aggiornate le librerie javascript utilizzando le versioni più recenti di jQuery (3.7.1) e Bootstrap (5.3.3)
• Nuovo frontend basato su Gradio 5.x
• Aggiunti test E2E con Playwright
• Aggiunta la possibilità di scrivere, leggere ed ovviamente valutare una frase a scelta libera
• Tour guidato per i nuovi utenti con driver.js ed css/javascript custom dentro ai Gradio blocks
• Riproduzione delle singole parole nella registrazione seguite dalla pronuncia 'ideale' della stessa parola letta dal motore Text-to-Speech
• Aggiunto anche una funzionalità di Text-to-Speech in-browser (su Windows 11 funziona solo nel caso siano installati i pacchetti linguistici inglesi e tedesco)
• Frontend custom webApp - migliorato lo stile CSS su dispositivi mobile

Versione online: la demo su HuggingFace

Potete provare online il mio progetto sul mio HuggingFace Space. Questa demo online vi permette di sperimentare le capacità dello strumento senza alcuna installazione o configurazione. Lo spazio HuggingFace fornisce un modo conveniente e accessibile per testare AI Pronunciation Trainer e vedere come può aiutarvi a migliorare la vostra pronuncia. Si prega di essere pazienti, a volte è un po' lento oppure in sleeping nel caso non sia utilizzato da nessuno da un po' (localmente è molto più veloce, soprattutto se avete un computer potente). Ecco una versione embedded dello spazio HuggingFace:

Sviluppi Futuri

Pur funzionando piuttosto bene, ci sono ovviamente margini di miglioramento. Ecco alcuni dei miglioramenti futuri che intendo implementare:

• Ricevere feedback dall'autore del progetto originale (Thiago Lobato) sulla mia documentazione e sulle modifiche
• Chiedere all'autore del lavoro originale alcune spiegazioni sulle scelte architetturali e funzionali che ha fatto
• Valutare il passaggio da PyTorch a onnxruntime (se possibile)
• Aggiungere nuovamente il container docker (se possibile)

Conclusione

AI Pronunciation Trainer è uno strumento utile per chiunque desideri migliorare in autonomia la propria pronuncia. Con la potenza dell'IA ed i miglioramenti apportati durante il refactor, questo strumento fornisce feedback accurati e affidabili per aiutarvi a parlare in modo più chiaro e sicuro. Vi invito a provare la demo HuggingFace Space e capire come questo progetto possa aiutarvi nel vostro percorso verso una migliore pronuncia.

In this article, I present the project I am working on: AI Pronunciation Trainer (online here), a tool designed to help you improve your pronunciation using the power of artificial intelligence. This project is a refactor of the original AI Pronunciation Trainer by Thiagohgl to which I have made several improvements to make the tool more effective and easier to use.

What it is and what it does

AI Pronunciation Trainer is a tool that uses AI to evaluate your pronunciation and provide feedback, helping you to improve and be understood more clearly. It leverages the Silero STT / TTS, openai whisper and faster whisper models for speech-to-text functionalities (Silero does also text-to-speech), ensuring accurate and reliable pronunciation assessment.

Refactor: upgraded frontend and backend libraries

About the backend:

• Updated PyTorch at version 2.6.x
• Updated Silero German Speech-to-Text model to resolve a bug that prevented the use of PyTorch versions later than 1.13.x
• Improved backend tests with the mutation test suite Cosmic Ray
• Fixed a bug with whisper not properly transcribing the end timestamp for the last word in the recorded audio (in the end I solved it switching to the openai whisper python pip package)
• Added faster whisper model support:
  • it avoids None values on end_ts timestamps for the last elements, unlike the HuggingFace Whisper's output
  • it uses silero-vad to detect long silences within the audio

Furthermore, regarding the frontend:

• Updated the JavaScript libraries using the latest versions of jQuery (3.7.1) and Bootstrap (5.3.3)
• New frontend based on Gradio 5.x
• Added E2E tests with Playwright
• Added the ability to insert custom sentences to read and evaluate
• Onboarding tour for new users made with driver.js and custom css/javascript in Gradio blocks
• Playback of individual words in the recording followed by the 'ideal' pronunciation of the same word read by the Text-to-Speech engine
• Also added an in-browser Text-to-Speech functionality (on Windows 11, it only works if the English and German language packs are installed)
• Custom webApp frontend - improved CSS style on mobile devices

Online version: the HuggingFace Space Demo

You can try it online using the HuggingFace Space. This online demo allows you to experience the tool's capabilities without any installation or configuration. The HuggingFace Space provides a convenient and accessible way to test the AI Pronunciation Trainer and see how it can help you improve your pronunciation. Please be patient, sometimes it is a bit slow or in sleeping mode (locally it is much faster, especially if you have a powerful computer). Here is an embedded version of my HuggingFace Space:

Future Work

Although this tool works pretty good, there are still some areas for improvement. Here are some of the future enhancements I plan to implement:

• Receive feedback from the original project author (Thiago Lobato) on my documentation and changes
• Ask the original author for explanations on the architectural and functional choices he made
• Explore transitioning PyTorch to onnxruntime (if possible)
• Re-add the docker container (if possible)

Conclusion

AI Pronunciation Trainer is a valuable tool for anyone looking to improve their pronunciation. With the power of AI and the improvements made in the refactoring project, this tool provides accurate and reliable feedback to help you speak more clearly and confidently. I invite you to try the HuggingFace Space demo and understand how this little project can help you on your journey to better pronunciation.

Una giornata di trekking in Val Trela ​​passando per il Lago Nero

Alcuni angoli della Val Trela e del Lago Nero

Photos taken on 6 August 2024.

A Trekking day in Val Trela passing by Lago Nero

Different sides of Val Trela and Lago Nero

Photos taken on 6 August 2024.

Per una comprensione di base del mio progetto, si veda questa e questa pagina.

Oggi invece sto scrivendo della mia nuova demo utilizzando un hardware ZeroGPU. Si noti che ZeroGPU Spaces è attualmente in versione beta. Gli utenti PRO o le Enterprise organizations possono creare i propri space ZeroGPU a loro nome. Inoltre è necessario pagare ogni mese per mantenere il diritto di utilizzare l'hardware ZeroGPU.

• Ho riscontrato inizialmente dei problemi causati dall’uso del decoratore spaces.GPU su una funzione inappropriata la cui esecuzione richiedeva troppo tempo, causando timeout. Risolto facendo debug per usare il decoratore solo sulle funzioni che ne richiedevano effettivamente l’uso.
• Frontend custom: non mi piace molto svelte (la libreria js scelta dal team di Gradio) ma soprattutto ho già un progetto ben avviato scritto in vuejs e vite che voglio riutilizzare. Risolto facendo l’installazione del pacchetto Debian nodejs 18 per poi installare le dipendenze e fare la build del progetto nodejs direttamente da dentro il file app.py usando subpropcess.run().

Nota che sto usando un periodo di timeout di 48 ore prima di mettere in pausa il mio space. Qualsiasi interazione successiva potrebbe richiedere un po' di tempo prima che lo space riparta.

Ultimo, ma non ultimo, la pagina della demo è online qui (interfaccia Gradio) e qui (la mia pagina SPA custom).

See this and this page for a basic understand of what is about my project.

Today instead I'm writing about my new demo on ZeroGPU space. Note that ZeroGPU Spaces is currently in beta. PRO users or Enterprise organizations can host their own ZeroGPU Spaces under their namespaces. Also there is need to pay every month for keep the right to use ZeroGPU hardware.

• I solved some problems caused by spaces.GPU decorator on a function which execution time was too high, causing a timeout. To solve it I started debugging and I ended using spaces.GPU only on functions that really needed the GPU acceleration.
• I don't like very much svelte (the js library chosen by Gradio team) and I already have a vuejs/vite frontend project that I can re-use. I solved this installing the nodejs 18 Debian package and starting the nodejs build from within the app.py file using subpropcess.run().

Note that I'm using a timeout period of 48h before putting my space in pause. Any interaction after that could take a while until the space restart.

Last but not least there is my online demo here (Gradio interface) and here (my custom SPA page).

Read publications related to the projects I work on

To improve my understanding of my machine learning project I decided to read the papers on which LISA and Segment Anything are based. Besides some theoretical informations about LLM, I noticed that the modular architecture of "SAM" permits to save and re-use image embeddings. Since SamGIS didn't work this way initially, I formulated an hypothesis about this.

Debugging, measures and optimization: Image Embedding Hypothesis

At this point I continued my debugging work by measuring the duration of individual steps during the execution of SamGIS functions. Creating an image embedding is quite an expensive operation, so it is advantageous saving it and re-using it (I verified that implementing my hypothesis would improve the performance of the software). Using the HuggingFace hardware profile "Nvidia T4 Small" (with 4 vCPU, 15 GB RAM and 16 GB VRAM) it's possible to save almost 1 second on every inference after the first, using the same image (without change the geographical area tiles provider).

The role of LLMs with prompts having different characteristics

LISA inherits the language generation capabilities of multi-modal LLMs such as Llava. These models excel at handling complex reasoning, world knowledge, explanatory answers and multi-turn conversations. They’re powerful tools for bridging the gap between text and visual understanding.

LISA allows you to perform rather complex reasoning during image segmentation (e.g. "identify the houses near the trees..." vs "identify the houses...") without any particular performance degradation. On the contrary, requests containing the explanation of reason ("explain why") the segmentation task is done in a certain way will have much higher execution times (in the order of minutes).

There are more details here about these improvements following the changes described and regarding different performance due to different cases when using SamGIS with LISA.

Leggere le pubblicazioni inerenti ai progetti su cui lavoro

Per migliorare la mia comprensione del mio progetto di machine learning ho deciso di leggere l'articolo su cui si basano LISA e Segment Anything. Oltre ad alcune informazioni teoriche su LLM, ho notato che l'architettura modulare di "SAM" consente di creare e riutilizzare gli image embedding. Dato che SamGIS non funzionava in questo modo inizialmente, ho formulato un'ipotesi al riguardo.

Debug, misure ed ottimizzazione: ipotesi sul image embedding

A questo punto ho continuato il mio lavoro di debug misurando la durata dei singoli passaggi durante l'esecuzione delle funzioni di SamGIS. La creazione di un image embedding è un'operazione abbastanza onerosa, quindi è vantaggioso salvarlo e riutilizzarlo (ho verificato implementare la mia ipotesi migliorerebbe le prestazioni del software). Utilizzando il profilo hardware HuggingFace "Nvidia T4 Small" (con 4 vCPU, 15 GB RAM e 16 GB VRAM) è possibile risparmiare circa 1 secondo per ogni inferenza successiva alla prima, utilizzando la stessa immagine (quindi senza modificare il tile provider e l'area geografica).

Il ruolo dei LLM con prompt aventi differenti caratteristiche

LISA eredita le capacità di generazione del linguaggio dei LLM multi-modali come Llava. Questi modelli eccellono nella gestione di ragionamenti complessi, conoscenza del mondo, risposte esplicative e conversazioni a più turni. Sono strumenti potenti per colmare il divario tra testo e comprensione visiva.

LISA permette di effettuare ragionamenti piuttosto complessi durante la segmentazione delle immagini (es. "identify the houses near the trees..." vs "identify the houses...") senza particolari peggioramenti prestazionali. Al contrario, richieste contenenti la spiegazione del motivo ("explain why") per cui il task di segmentazione sia fatto in un certo modo avranno tempi di esecuzione molto più elevati (nell'ordine di minuti).

Sono disponibili maggiori dettagli qui su questi miglioramenti in seguito alle modifiche descritte e relativamente alle differenti prestazioni dovute a diversi casi durante l'utilizzo di SamGIS con LISA.

From the Segment Anything paper

"SAM" is a foundation model aiming for performing "zero-shot" image segmentation:

• it's build and trained with a large image dataset with a massive amount of segmentation masks
• the SAM team propose the "promptable" segmentation task, where the goal is to return a valid segmentation mask given any segmentation prompt.

Since this model should perform "zero-shot" segmentation the model must support flexible prompts, needs to compute masks in amortized real-time to allow interactive use and must be ambiguity-aware. That's the model architecture:

1. source 1: an image encoder computes an image embedding
2. source 2: a fast prompt encoder embeds prompts
3. output: a fast mask decoder combines these two sources to predict segmentation masks

Because annotation masks are not abundant online, especially of high quality, the SAM developers opted for developing a "data engine", developing both the model and the dataset annotations (from manual stage to semi-automated to fully automated). Images in SA-1B span a geographically and economically diverse set of countries and we found that SAM performs similarly across different groups of people.

Segment Anything Tasks

Task

Here SAM team translate prompts from NLP to segmentation (selecting/de-selecting points, box, mask, free-form text). Like a language model should output a coherent response to an ambiguous prompt, the promptable segmentation task should return a valid segmentation mask given any prompt.

Pre-Training

The promptable segmentation task suggests a natural pre-training algorithm that simulates a sequence of prompts (e.g., points, boxes, masks) for each training sample and compares the model’s mask predictions against the ground truth.

Segment Anything Model

Image encoder

The algorithm use a MAE ("Masked Autoencoders Are Scalable Vision Learners") pre-trained Vision Transformer (ViT) minimally adapted to process high resolution inputs.

Prompt encoder

SAM supports two sets of prompts:

• sparse (points, boxes, text)
• dense (masks)

SAM prompts handle points and boxes by positional encodings summed with learned embeddings for each prompt type. Dense prompts (i.e., masks) are embedded using convolutions and summed element-wise with the image embedding.

Mask decoder

The mask decoder efficiently maps the image embedding, prompt embeddings, and an output token to a mask. This design employs a modification of a Transformer decoder block followed by a dynamic mask prediction head. The decoder block uses prompt self-attention and cross-attention in two directions (prompt-to-image embedding and vice-versa) to update all embeddings. After running two blocks, the procedure upsample the image embedding and an MLP maps the output token to a dynamic linear classifier, which then computes the mask foreground probability at each image location.

Resolving ambiguity

With one output, to avoid masks merging in case of an ambiguous prompt the model can predict more than one output mask for a single prompt. 3 masks should address most common cases (nested masks are often at most three deep: whole, part, and subpart). During training, the procedure backprops only the minimum loss over masks. To rank masks, the model predicts a confidence score (i.e., estimated IoU) for each mask.

About image embedding re-use and SamGIS

After reading this paper I understood that I could improve SamGIS software design storing and re-using the image embeddings.

I implemented this change in SamGIS version 1.3.0. Some test data from the SamGIS demo I used:

• first request: 5.42s
  • instantiated fastsam model
  • created image from webmap (I'm using OpenStreetMap as tiles provider and Mapnik as map layer)
  • created image embedding
• second request: 0.41s
• from third to seventh request: ~0.34s

Note that making one request immediately after another keep requests duration low probably because of cache during tiles download on backend side. Instead waiting more than 10 minutes it seems invalidate the cache, then contextily (the GeoPandas' library that I use as a tiles client) added from 0.5s to 1.5s of time, during my tests, to download the tiles.

{
    "bbox": {
        "ne": {
            "lat": 46.236615111857255,
            "lng": 9.519996643066408
        },
        "sw": {
            "lat": 46.13405108959001,
            "lng": 9.29821014404297
        }
    },
    "prompt": [
        {
            "id": 146,
            "type": "point",
            "data": {
                "lat": 46.18483299780137,
                "lng": 9.418864745562386
            },
            "label": 1
        }
    ],
    "zoom": 13,
    "source_type": "OpenStreetMap"
}

About Zero-Shot Text-to-Mask: LISA and SamGIS

SAM can use also simple free-form text prompts. For a practical use of this feature, see:

• Grounded-SAM
• LISA

Of course could be of your interest also my integration work of LISA with SamGIS and its cuda demo. I need to keep it paused because of cost, but I am requesting the use of a free GPU from HuggingFace.

Right now there is a demo hardware-based ZeroGPU: it's a little bit slow compared with the regular cuda demo, but it's free to use (if I keep to pay the fee for PRO HuggingFace subscription).

If you like my project, please like or comment on the HuggingFace GPU resource request thread.

Rimando alle mie note in inglese su Segment Anything.

A proposito del riutilizzo degli embedding delle immagini e SamGIS

Dopo aver riletto questo paper ho capito che avrei potuto migliorare l'efficienza di SamGIS conservando e riutilizzando gli embedding delle immagini.

Ho implementato questa modifica in SamGIS versione 1.3.0. Alcuni dati di test dalla demo SamGIS che ho utilizzato:

• prima chiamata: 5.42s
  • modello fastsam istanziato
  • immagine creata dalla mappa web (uso OpenStreetMap come tile provider e Mapnik come layer della webmap)
  • creato il embedding dell'immagine
• seconda chiamata: 0,41 s
• dalla terza alla settima chiamata: ~0,34s

Si tenga presente che effettuando una chiamata immediatamente dopo l'altra la durata rimane bassa, probabilmente a causa dell'utilizzo della cache durante il download delle tile nel back-end. Aspettando più di 10 minuti sembra invalidare la cache, quindi contextily (la libreria di GeoPanda che utilizzo come client di Tiles) ha impiegato da 0.5s a 1.5s di tempo, durante le mie prove, per il download delle tile.

{
    "bbox": {
        "ne": {
            "lat": 46.236615111857255,
            "lng": 9.519996643066408
        },
        "sw": {
            "lat": 46.13405108959001,
            "lng": 9.29821014404297
        }
    },
    "prompt": [
        {
            "id": 146,
            "type": "point",
            "data": {
                "lat": 46.18483299780137,
                "lng": 9.418864745562386
            },
            "label": 1
        }
    ],
    "zoom": 13,
    "source_type": "OpenStreetMap"
}

A proposito della conversione "dal testo alla maschera" "zero shot": LISA e SamGIS

La versione originale di SAM può utilizzare anche semplici prompt testuali in linguaggio naturale. Per un uso pratico di questa funzionalità, si veda:

• Grounded-SAM
• LISA

Naturalmente potrebbe interessare anche il mio lavoro di integrazione di LISA con SamGIS e la corrispondente [demo](https://huggingface. co/spaces/aletrn/samgis-lisa-on-cuda). Devo tenerlo in pausa a causa dei costi, ma sto richiedendo l'uso di una GPU gratuita da HuggingFace.

Al momento è disponibile una demo basata su hardware ZeroGPU: è un po' lenta rispetto alla demo cuda classica, ma è gratuita (nel caso io continui a pagare la quota per l'abbonamento PRO HuggingFace).

Nel caso il mio progetto fosse interessante, metti "mi piace" o commenta il [thread di richiesta di risorse GPU di HuggingFace](https://huggingface.co /spaces/aletrn/samgis-lisa-on-cuda/discussions/1).

La segmentazione d'immagine è un compito cruciale nella visione artificiale, dove l'obiettivo di fare "instance segmentation" di un dato oggetto. Ho già lavorato ad un progetto, SamGIS, a riguardo. Un passo logico successivo sarebbe integrare la capacità di riconoscere gli oggetti attraverso prompt testuali. Quest'attività apparentemente semplice in effetti comporta però delle differenze rispetto a quanto fatto in SamGIS che utilizza Segment Anything (il backend di machine learning usato da SamGIS). Mentre infatti "SAM" non categorizza ciò che identifica, partire da un prompt scritto necessita della conoscenza di quali classi di oggetti esistano nell'immagine in analisi. Un modello di linguaggio visivo (o VLM) che funziona bene per questo compito è LISA. Gli autori di LISA hanno basato il loro lavoro su Segment Anything e Llava, un LLM con capacità multimodali (può elaborare sia istruzioni di testo che immagini). Sfruttando le capacità di "segmentazione ragionata" di LISA, SamGIS può eseguire analisi di tipo "zero-shot", ovvero senza addestramento pregresso specifico e specialistico in ambito geologico, geomorfologico o fotogrammetrico.

Prompts testuali d'input e relativi geojson di output

Ho esportato l'immagine in overlay usando come sorgente il provider di tiles Esri.WorldImagery.

Si noti che ho aggiunto alcuni prompt testuali complessi come "devi individuare le case vicino alle strade". In alcuni casi i risultati sono migliori di altri e questo può cambiare grazie a LLM più avanzati o con un numero maggiore di parametri.

{
    "bbox": {
        "ne": {
            "lat": 46.173968917056655,
            "lng": 10.082219839096071
        },
        "sw": {
            "lat": 46.16651671595163,
            "lng": 10.066105127334597
        }
    },
    "string_prompt": "You are a skilled gis analyst with a lot of expertise in photogrammetry, remote sensing and geomorphology field. You need to identify...",
    "zoom": 17,
    "source_type": "Esri.WorldImagery"
}

Durata dei task di segmentazione

Al momento, un prompt che richieda anche la spiegazione di quanto identificato nell'immagine rallenta notevolmente l'analisi. Lo stesso prompt d'analisi eseguito sulla stessa immagine però senza richieste di spiegazione viene elaborato molto più velocemente. I test contenenti richieste di spiegazioni vengono eseguiti in più di 60 secondi mentre senza la durata è intorno o inferiore a 4 secondi, utilizzando il profilo hardware HuggingFace "Nvidia T4 Small" con 4 vCPU, 15 GB RAM e 16 GB VRAM.

Architettura software

Dal punto di vista tecnico e architetturale, la demo consiste di un frontend simile a quello sulla demo di SamGIS. Niente barra degli strumenti per disegnare, sostituita dalla casella di testo per le richieste in linguaggio naturale. Il backend utilizza un'API basata su FastAPI e che invoca una funzione ad hoc basata su LISA.

Ho dovuto mettere in pausa la demo a causa del costo della GPU, ma sto richiedendo l'uso di una GPU gratuita da HuggingFace. Non esitate a contattarmi su LinkedIn per una dimostrazione dal vivo, chiedere maggiori informazioni o ulteriori chiarimenti.

Al momento è disponibile anche una demo basata su hardware ZeroGPU: è un po' lenta rispetto alla demo cuda classica, ma è gratuita (nel caso io continui a pagare la quota per l'abbonamento PRO HuggingFace). Si noti che lo spazio ZeroGPU potrebbe essere in pausa per inattività e, nel caso, servirà attendere per il suo completo caricamento.

Image segmentation is a crucial task in computer vision, where the goal is to extract the instance segmentation mask for a desired object within the image. I've already worked on a project, SamGIS, that focuses on this particular application of computer vision. A logical progression now would be incorporating the ability to recognize objects through text prompts. This apparently simple activity is actually different compared to what Segment Anything (the ML backend used by SamGIS) does. In fact "SAM" does not outputs descriptions nor categorizations for its input images. Starting from a written prompt at the contrary requires understanding which classes of objects exist in the image under analysis. A visual language model (or VLM) that performs well for this task is LISA. LISA's authors built their work on top of Segment Anything and Llava, a large language model with multimodal capabilities (it can process both text prompts and images). By leveraging LISA's "reasoned segmentation" abilities, SamGIS can now conduct "zero-shot" analyses, meaning it can operate without specific or specialistic prior training in geological, geomorphological, or photogrammetric fields.

Some input text prompts with their geojson outputs

I exported the image in overlay from Esri.WorldImagery tiles provider.

Note that I added some complex text prompts like "you need to segment the houses near roads". In some cases the results are better than others and this can change thanks to more advanced LLMs or with a greater number of parameters.

{
    "bbox": {
        "ne": {
            "lat": 46.173968917056655,
            "lng": 10.082219839096071
        },
        "sw": {
            "lat": 46.16651671595163,
            "lng": 10.066105127334597
        }
    },
    "string_prompt": "You are a skilled gis analyst with a lot of expertise in photogrammetry, remote sensing and geomorphology field. You need to identify...",
    "zoom": 17,
    "source_type": "Esri.WorldImagery"
}

Duration of segmentation tasks

At the moment, a prompt that also requires an explanation about the segmentation task slows down greatly the analysis. The same prompt on the same image without "descriptive" or "explanatory" questions instead finish much faster. Tests with explanatory text perform in more than 60 seconds while without duration is between 3 and 8 seconds, using the HuggingFace hardware profile "Nvidia T4 Small" with 4 vCPU, 15 GB RAM and 16 GB VRAM.

Software architecture

Technically and architecturally, the demo consists of a frontend page like SamGIS demo. Instead of the drawing tool bar there is a text prompt for natural language requests with some selectable examples displayed at the top of the page. The backend utilizes a FastAPI-based API that calls a custom LISA function wrapper.

Unfortunately I have to pause my demo due to GPU cost, but I am requesting the use of a free GPU from HuggingFace. Please feel free to reach out to me on LinkedIn for a live demonstration, ask for more information or further clarifications.

Right now there is also a demo hardware-based ZeroGPU: it's a little bit slow compared with the regular cuda demo, but it's free to use (if I keep to pay the fee for PRO HuggingFace subscription). Please note that the ZeroGPU space may be paused due to inactivity and you will need to wait for it to fully load.

Sci nordico a San Giuseppe

Qualche foto di San Giuseppe

Scatti effettuati il 28 Gennaio 2024.

Nordic skiing in San Giuseppe

Let's take some photos of San Giuseppe

Photos taken on 28 January 2024.

It's a way in which a machine is able to perform tasks without explicit programming. Theoretical bases have existed since the 1960s, but significant results are possible thanks to dedicated hardware, algorithms capable of exploiting this power and well structured datasets.

A classification example

A software programmed explicitly to perform image classification would need to identify explicitly the characteristics of the object. This can work if all objects are reasonably simple and similar. But what if the some features of the same object category have an high variance?

An approach without explicit instructions

We could submit a suitably labeled dataset of image data to the software (i.e. the machine learning model) by performing an appropriate number of training-and-testing cycles on it. Another example could use linear regression to predict prices of houses by their sizes. The common ground here is study the data to form an hypothesis. Adding more data probably will expose errors within the hypothesis, then we can measure the error gap and form an updated hypothesis with a minor error gap.

The machine has to analyze the dataset using some assumptions, e.g. a linear variable that can be represented as a straight line on a Cartesian plane. The machine goal is to test every possibile result to extract the one with the lowest error rate. It's simple with a linear variable, much more complex with some modern machine learning models that have billions of variables, but the principle is the same: the machine start from a random point (or parameters set) and move towards the lowest error rate, cycle after cycle of train and test.

Every train-and-test step give a measure (an "error function" or "loss function") and the repetition of these steps is the "gradient descent" towards the solution.

There are various ways to improve results such as backpropagation to fine-tune the data parameters and neural node dropouts to reduce overfitting (when the ML model is no longer can generalize well on real world data).

Some machine learning categories

• supervised learning: image classification, speech/text recognition, fraud detection
• unsupervised learning: grouping data into clusters or identifying anomalies
• reinforcement learning: the software finds the best solution for a given problem

Sources to learn more

• AI and machine learning products
• Deep Learning with Python, Second Edition, by François Chollet
• IBM: What is machine learning?
• Machine learning, cos’è e come funziona questa branca dell’intelligenza artificiale
• Large language models, explained with a minimum of math and jargon

È un sistema in cui una macchina può eseguire compiti senza programmazione esplicita. Le basi teoriche esistono fin dagli anni '60, ma risultati significativi sono possibili (dal 2013 in poi circa) grazie ad hardware dedicato, algoritmi in grado di sfruttarne la potenza e dataset di dati ben strutturati e catalogati.

Un esempio di classificazione

Un software programmato esplicitamente per eseguire la classificazione delle immagini dovrebbe identificare esplicitamente le caratteristiche dell'oggetto. Questo può funzionare se tutti gli oggetti in questione sono ragionevolmente semplici e simili. Ma cosa succede se alcune caratteristiche della stessa categoria di oggetti presentano una varianza elevata?

Un approccio senza istruzioni esplicite

Potremmo sottoporre al software (ovvero il modello di machine learning) un dataset di dati di immagine opportunamente etichettato eseguendo su di esso un numero opportuno di cicli di training e test. Un altro esempio potrebbe utilizzare la regressione lineare per prevedere i prezzi delle case in base alle loro dimensioni. Le caratteristiche comuni di questi due esempi sono lo studio dei dati per formare un’ipotesi. L'aggiunta di più dati probabilmente esporrà errori all'interno dell'ipotesi, quindi potremo misurare il divario di errore e formare un'ipotesi aggiornata con un divario di errore minore.

La macchina deve analizzare il set di dati utilizzando alcune ipotesi, ad es. una variabile lineare rappresentabile come una retta su un piano cartesiano. L'obiettivo della macchina è testare ogni possibile risultato per estrarre quello con il tasso di errore più basso. È semplice con una variabile lineare, molto più complesso con alcuni moderni modelli di machine learning che hanno miliardi di variabili, ma il principio è lo stesso: la macchina parte da un punto (o set di parametri) casuale e si muove verso il tasso di errore più basso, ciclo dopo ciclo di treno e prova.

Ogni passaggio di training e test fornisce una misura (una "funzione di errore" o "funzione di perdita") e la ripetizione di questi passaggi è il "gradiente di discesa" verso la soluzione.

Esistono vari modi per migliorare i risultati come la backpropagation per ottimizzare i parametri dei dati e [gli abbandoni dei nodi neurali](https://machinelearningmastery.com/dropout -for-regularizing-deep-neural-networks/) per ridurre l'overfitting (quando il modello ML non è più in grado di generalizzare bene sui dati del mondo reale).

Alcune categorie di machine learning

• apprendimento supervisionato: classificazione di immagini, riconoscimento del testo e vocale, rilevamento di frodi
• apprendimento non supervisionato: raggruppamento dei dati in cluster o individuazione di anomalie
• apprendimento per rinforzo: il software trova la soluzione migliore per un dato problema

Risorse per l'approfondimento

• AI and machine learning products
• Deep Learning with Python, Second Edition, di François Chollet
• IBM: cos'è il machine learning?
• Machine learning, cos’è e come funziona questa branca dell’intelligenza artificiale
• Large language models, explained with a minimum of math and jargon

When I started working on this Hugging Face demo version of SamGIS I needed also to deploy the static fronted. Since the Hugging Face backend uses Fastapi I changed the way I use StaticFiles() this way:

app.mount("/", StaticFiles(directory="static/dist", html=True), name="static")

Note that the static folder contains both the dist and the node_modules folder:

static/
├── dist
│   ├── assets
│   │   └── index-FDtpfbXx.js
│   ├── index.html
│   ├── output.css
│   └── ... png, svg, etc
└── node_modules
    └── ...

9 directories, 22 files

Remember that to use a tailwind css it's necessary to add a dedicated build within the dockerfile like this:

# dockerfile

RUN --mount=type=cache,id=pnpm,target=/pnpm/store if [ "${DEPENDENCY_GROUP}" = "fastapi" ]; then \
    pnpm build; fi
RUN --mount=type=cache,id=pnpm,target=/pnpm/store if [ "${DEPENDENCY_GROUP}" = "fastapi" ]; then \
    pnpm tailwindcss -i /appnode/src/input.css -o /appnode/dist/output.css; fi

That's the way you do it an easy task!

Quando ho iniziato a lavorare su questa versione demo di Hugging Face di SamGIS avevo bisogno anche per implementare il frontend statico. Dato che il backend di Hugging Face utilizza Fastapi modificato l'utilizzo di StaticFiles() così:

app.mount("/", StaticFiles(directory="static/dist", html=True), name="static")

Si tenga presente che la cartella static contiene sia la cartella dist che la cartella node_modules:

static/
├── dist
│   ├── assets
│   │   └── index-FDtpfbXx.js
│   ├── index.html
│   ├── output.css
│   └── ... png, svg, etc
└── node_modules
    └── ...

9 directories, 22 files

Per utilizzare un css prodotto da tailwind serve aggiungere uno step di build dedicato all'interno del dockerfile:

#dockerfile

RUN --mount=type=cache,id=pnpm,target=/pnpm/store if [ "${DEPENDENCY_GROUP}" = "fastapi" ]; then \
    pnpm build; fi
RUN --mount=type=cache,id=pnpm,target=/pnpm/store if [ "${DEPENDENCY_GROUP}" = "fastapi" ]; then \
    pnpm tailwindcss -i /appnode/src/input.css -o /appnode/dist/output.css; fi

Questo è il modo in cui si fa in un lavoretto semplice!

This project, composed by a SPA frontend and by a backend (samgis-be), is an attempt to perform machine learning image segmentation on geo-spatial data even without the use of dedicated graphics cards. I recently added the ability to start from natural language text prompts.

I wrote the backend adapting SAM Exporter with the aim to use the machine learning segment anything project for the purpose to improve polygons recognition in GIS web applications.

Starting from version 1.5.1 the backend integrates changes borrowed from sam_onnx_full_export, to support OnnxRuntime 1.17.x and later versions. Please note that on MacOS directly running the project from the command line suffers from memory leaks, making inference operations slower than normal. It's best therefore running the project inside a docker container, unless in case of development or debugging activities.

These are the project resource links:

• a public HuggingFace space demo
• the documentation and AWS lambda OpenAPI specs

Note that the HuggingFace space demo has its static frontend files under the /static folder.

Ask me for a user via linkedin if you would like to test the authenticated demo or an explanation about the code.

LISA and SamGIS

I also added support for image segmentation via natural language text prompts: here are the details about the SamGIS integration with LISA.

SamGIS also replaces SurferDTM

SurferDTM was an attempt to find stratovolcanoes within digital terrain models (DEM/DTM). As a new feature SamGIS now can now use also input DEM images (like the first image in this gallery):

Note that the "terrarium" source provider data encode the image as RGB, so the backend processes it to obtain the elevation data (like the second image in this gallery) using this formula (from the map tile provider page):

(red * 256) + green + (blue / 256) - 32768

I also added a custom elaboration step to create an intermediate RGB image composed by channels:

• RED - normalized DEM image
• GREEN - normalized 2d composed image by
  • normalized DEM image
  • slope
  • curvature
• BLUE - curvature

Segment Anything will finally do the inference on this rgb image.

{
   "bbox": {
         "ne": {"lat": 46.203706648934954, "lng": 9.401906739170105},
         "sw": {"lat": 46.12464369105346, "lng": 9.231103669101747}},
   "prompt": [
         {"id": 238, "type": "point", "data": {"lat": 46.158760519552146, "lng": 9.306795638666486}, "label": 1},
         {"id": 250, "type": "point", "data": {"lat": 46.152693546080975, "lng": 9.289288652508679}, "label": 0},
         {"id": 264, "type": "point", "data": {"lat": 46.16613515509541, "lng": 9.319840059725284}, "label": 0},
         {"id": 272, "type": "point", "data": {"lat": 46.161377438862836, "lng": 9.288087192674299}, "label": 0},
         {"id": 285, "type": "point", "data": {"lat": 46.174103408003454, "lng": 9.308340372739261}, "label": 0},
         {"id": 293, "type": "point", "data": {"lat": 46.17005996124035, "lng": 9.298042145587583}, "label": 0}
   ],
   "zoom": 13,
   "source_type": "nextzen.terrarium"
}

Project Architecture of AWS demo

1. The user interact with a WebMap (in my example it's a leaflet map that use OpenStreetMap map data).

2. The user send a POST request to an API using

   1. the current map extent
   2. the current map zoom
   3. a prompt array of objects; objects could be
      • an "include" marker position (a couple of float - latitude and longitude)
      • an "exclusionary" marker position (a couple of float - latitude and longitude)
      • a "include" rectangle (two latitude and longitude positions - north-east and south-west)

3. because of CORS constrain it's difficult to directly send requests to remote resources on different domains: to avoid this problems I prepared a simple Cloudflare proxy function that forward the user request to the remote API

4. The API Gateway proxies the request to the serverless backend

5. the serverless Lambda API elaborate the request:

   1. it parses the request and in particular translate the input latitude/longitude prompt into a x/y (pixel coordinates) one
   2. it downloads the geo-referenced tiles then merge and crop them
   3. it instantiates a MobileSam model instance if not already created using OnnxRuntime as runtime
   4. it prepares the image embedding and...
   5. ...it starts the image inference process
   6. it transforms the recognition masks into a single binary mask then it vectorizes the recognized binary mask:
      1. first it converts the mask into a GeoPandas GeoDataframe using rasterio.features.shapes and GeoDataFrame.from_features
      2. then it convert the new Geodataframe into a geojson using GeoDataFrame.to_json

6. the Cloudflare proxy function parses the response and forward it to the frontend

7. the frontend parse the geojson to load within the WebMap and shows some response info like the non-relativistic response duration time:

   

To avoid abuse the prompt input web map that I host on my personal site is under authentication (I use auth0.com).

Fastapi-based demo architecture

This project variant works almost as this. There are these differences:

• opencv-python is not anymore a SamGIS project dependency
• the server now saves and re-uses image embeddings to avoid resource waste and speed up the inference process
• SPA frontend now is integrated directly within the Fastapi backend

Frontend and backend now are on the same domain. Therefore there is no longer use for a proxy (the AWS demo used a Cloudflare Pages function) to make requests to APIs on a different domain.

Additionally, since I can host this Fastapi demo for free on HuggingFace, I don't need anymore an authentication system.

AWS lambda, a serverless solution: some pros...

• It can work also with docker images for complex or big projects (like this)
• Almost easy, working out-of-the-box integration with other AWS services and third-parts authentication systems
• Pay-as-you-go service

...and some cons

• Setup not always easy (I used Powertools for AWS Lambda (Python) to improve my logger setup)
• The serverless model suggested by AWS not always it's the best solution
• Arm graviton EC2 instances that run AWS lambda are greatly limited (OnnxRuntime at the moment cannot run on Arm AWS lambda and probably will never run).

Questo progetto, composto da frontend SPA e da una parte backend (samgis-be), è un tentativo di effettuare riconoscimento d'immagine basato sul machine learning su immagini derivanti da dati geo-spaziali anche senza l'utilizzo di capacità computazionali particolari. Di recente ho aggiunto la possibilità di partire da prompt testuali in linguaggio naturale.

La prima versione del backend era modificata da SAM Exporter semplificando l'utilizzo di segment anything al fine di migliorare il riconoscimento di poligoni in applicazioni web GIS.

Dalla versione 1.5.1 il backend integra modifiche mutuate da sam_onnx_full_export, in modo da supportare OnnxRuntime 1.17.x e versioni successive. Si noti che su MacOS l'esecuzione diretta da linea di comando soffre di memory leak, rendendo le operazioni di inferenza più lente di quanto sarebbe normale. Si consiglia quindi l'esecuzione del progetto dentro ad un container docker, a meno di voler fare attività di sviluppo e debug.

Questi sono i link alle risorse del progetto:

• una demo di HuggingFace Space pubblica
• la documentazione e le specifiche AWS lambda OpenAPI

Si tenga presente che la demo dello spazio HuggingFace ha i suoi file frontend statici nella cartella /static.

Chiunque desideri una spiegazione dettagliata sul funzionamento di questo progetto oppure voglia testare la demo sotto autenticazione può contattarmi tramite linkedin.

LISA e SamGIS

Ho anche aggiunto il supporto alla segmentazione d'immagine tramite prompt testuali in linguaggio naturale: qui i dettagli a proposito dell'integrazione di SamGIS con LISA.

SamGIS rimpiazza anche SurferDTM

SurferDTM è un tentativo di trovare stratovulcani all'interno di modelli digitali del terreno (DEM/DTM). Come nuova funzionalità, SamGIS ora può utilizzare anche DEM di input (come la prima immagine in questa galleria):

Si tenga conto che il provider dei dati "terrarium" codifica le immagini come RGB, quindi il backend le elabora per ottenere le quote di terreno effettive (come nella seconda immagine in questa galleria) utilizzando questa formula (dalla pagina del provider, mapzen/nextzen):

(red * 256) + green + (blue / 256) - 32768

I also added a custom elaboration step to create an intermediate RGB image composed by channels:

• ROSSO - immagine DEM normalizzata
• VERDE - immagine 2d normalizzata composta dalla risultante di
  • immagine DEM normalizzata
  • slope
  • curvatura
• BLU - curvatura

Quest'immagine RGB infine sarà sottoposta a Segment Anything per l'inferenza.

{
   "bbox": {
         "ne": {"lat": 46.203706648934954, "lng": 9.401906739170105},
         "sw": {"lat": 46.12464369105346, "lng": 9.231103669101747}},
   "prompt": [
         {"id": 238, "type": "point", "data": {"lat": 46.158760519552146, "lng": 9.306795638666486}, "label": 1},
         {"id": 250, "type": "point", "data": {"lat": 46.152693546080975, "lng": 9.289288652508679}, "label": 0},
         {"id": 264, "type": "point", "data": {"lat": 46.16613515509541, "lng": 9.319840059725284}, "label": 0},
         {"id": 272, "type": "point", "data": {"lat": 46.161377438862836, "lng": 9.288087192674299}, "label": 0},
         {"id": 285, "type": "point", "data": {"lat": 46.174103408003454, "lng": 9.308340372739261}, "label": 0},
         {"id": 293, "type": "point", "data": {"lat": 46.17005996124035, "lng": 9.298042145587583}, "label": 0}
   ],
   "zoom": 13,
   "source_type": "nextzen.terrarium"
}

Architettura della demo AWS

1. L'utente interagisce con una WebMap (nel mio esempio è una mappa leaflet che utilizza i dati cartografici di OpenStreetMap).

2. L'utente invia una POST ad un'API utilizzando

   1. le coordinate estreme della vista corrente della mappa
   2. lo zoom corrente della mappa
   3. un prompt contenente
   • un marker "inclusivo", marcando quindi la posizione come inclusa (a couple of float - latitude and longitude)
   • un marker "escludente", marcando quindi la posizione come esclusa (a couple of float - latitude and longitude)
   • a "include" rectangle (a couple of marker positions - north-east and south-west)

3. a causa del vincoli posti dai CORS è difficile inviare direttamente richieste a risorse remote su domini diversi da quello di origine: per evitare questo problema ho preparato una semplice funzione proxy su Cloudflare (questo sito funziona con le Cloudflare Pages) che inoltra la richiesta dell'utente all'API remota

4. Il API Gateway inoltra la richiesta al backend serverless

5. La API Lambda serverless elabora la richiesta:

   1. analizza la richiesta e in particolare traduce il prompt con le coordinate di latitudine/longitudine in uno di coordinate x/y mappate sull'origine dell'immagine
   2. scarica le tiles georeferenziate per poi unirle e ritagliarle
   3. crea un'istanza del modello MobileSam se non esistente utilizzando OnnxRuntime come runtime
   4. prepara il embedding delle immagini e...
   5. ...avvia il processo di inferenza
   6. trasforma il array di maschere di oggetti riconosciuti in un'unica immagine binaria quindi vettorializza la maschera binaria riconosciuta:
      1. innanzitutto converte la maschera in un GeoDataframe GeoPandas utilizzando rasterio.features.shapes e GeoDataFrame.from_features
      2. quindi esporta il nuovo Geodataframe in un geojson utilizzando GeoDataFrame.to_json

6. la funzione proxy Cloudflare elabora la risposta e la inoltra al frontend

7. il frontend estrae dalla risposta il geojson che sarà poi caricato all'interno della WebMap. Sono anche aggiunte alcune informazioni come la durata non relativistica della risposta

   

Per evitare abusi la webmap dedicata a questo progetto sul mio sito personale è sotto autenticazione (utilizzo auth0.com).

Architettura della demo basata su Fastapi

Questa variante del progetto funziona in maniera abbastanza simile a questa. Queste le differenze principali:

• opencv-python non è più fra le dipendenze di SamGIS dalla versione 1.5.1
• il backend salva e riutilizza gli embedding delle immagini per evitare sprechi di potenza di calcolo e velocizzare il processo di inferenza
• il frontend SPA (Single Page Application) è esposto direttamente dall'applicazione Fastapi

Frontend e backend quindi risiedono sullo stesso dominio. Non servirà più quindi un proxy (la demo su AWS usava una Page function di Cloudflare) per fare richieste ad API su un dominio diverso.

Inoltre, posso mantenere online questa demo usando HuggingFace gratuitamente, rimuovendo la necessità di us sistema di autenticazione.

AWS lambda, una soluzione serverless: alcuni pro...

• Può funzionare anche con immagini docker, molto utile nel caso di progetti complessi
• Integrazione abbastanza semplice con altri servizi AWS e sistemi di autenticazione di terze parti
• Servizio a consumo

...e alcuni svantaggi

• Configurazione non sempre facile (ho utilizzato Powertools for AWS Lambda (Python) per migliorare la configurazione del mio logger)
• Il modello serverless suggerito da AWS non sempre è la soluzione migliore
• Le istanze Arm graviton EC2 che eseguono AWS lambda sono notevolmente limitate (OnnxRuntime al momento non può essere eseguito su AWS lambda Arm e probabilmente non sarà mai supportato).

Questo progetto, composto da frontend SPA e da una parte backend (samgis-be), è un tentativo di effettuare riconoscimento d'immagine basato sul machine learning su immagini derivanti da dati geo-spaziali anche senza l'utilizzo di capacità computazionali particolari. Di recente ho aggiunto la possibilità di partire da prompt testuali in linguaggio naturale.

La prima versione del backend era modificata da SAM Exporter semplificando l'utilizzo di segment anything al fine di migliorare il riconoscimento di poligoni in applicazioni web GIS.

Dalla versione 1.5.1 il backend integra modifiche mutuate da sam_onnx_full_export, in modo da supportare OnnxRuntime 1.17.x e versioni successive. Si noti che su MacOS l'esecuzione diretta da linea di comando soffre di memory leak, rendendo le operazioni di inferenza più lente di quanto sarebbe normale. Si consiglia quindi l'esecuzione del progetto dentro ad un container docker, a meno di voler fare attività di sviluppo e debug.

Questi sono i link alle risorse del progetto:

• una demo di HuggingFace Space pubblica
• la documentazione e le specifiche AWS lambda OpenAPI

Si tenga presente che la demo dello spazio HuggingFace ha i suoi file frontend statici nella cartella /static.

Chiunque desideri una spiegazione dettagliata sul funzionamento di questo progetto oppure voglia testare la demo sotto autenticazione può contattarmi tramite linkedin.

LISA e SamGIS

Ho anche aggiunto il supporto alla segmentazione d'immagine tramite prompt testuali in linguaggio naturale: qui i dettagli a proposito dell'integrazione di SamGIS con LISA.

SamGIS rimpiazza anche SurferDTM

SurferDTM è un tentativo di trovare stratovulcani all'interno di modelli digitali del terreno (DEM/DTM). Come nuova funzionalità, SamGIS ora può utilizzare anche DEM di input (come la prima immagine in questa galleria):

Si tenga conto che il provider dei dati "terrarium" codifica le immagini come RGB, quindi il backend le elabora per ottenere le quote di terreno effettive (come nella seconda immagine in questa galleria) utilizzando questa formula (dalla pagina del provider, mapzen/nextzen):

(red * 256) + green + (blue / 256) - 32768

I also added a custom elaboration step to create an intermediate RGB image composed by channels:

• ROSSO - immagine DEM normalizzata
• VERDE - immagine 2d normalizzata composta dalla risultante di
  • immagine DEM normalizzata
  • slope
  • curvatura
• BLU - curvatura

Quest'immagine RGB infine sarà sottoposta a Segment Anything per l'inferenza.

{
   "bbox": {
         "ne": {"lat": 46.203706648934954, "lng": 9.401906739170105},
         "sw": {"lat": 46.12464369105346, "lng": 9.231103669101747}},
   "prompt": [
         {"id": 238, "type": "point", "data": {"lat": 46.158760519552146, "lng": 9.306795638666486}, "label": 1},
         {"id": 250, "type": "point", "data": {"lat": 46.152693546080975, "lng": 9.289288652508679}, "label": 0},
         {"id": 264, "type": "point", "data": {"lat": 46.16613515509541, "lng": 9.319840059725284}, "label": 0},
         {"id": 272, "type": "point", "data": {"lat": 46.161377438862836, "lng": 9.288087192674299}, "label": 0},
         {"id": 285, "type": "point", "data": {"lat": 46.174103408003454, "lng": 9.308340372739261}, "label": 0},
         {"id": 293, "type": "point", "data": {"lat": 46.17005996124035, "lng": 9.298042145587583}, "label": 0}
   ],
   "zoom": 13,
   "source_type": "nextzen.terrarium"
}

Architettura della demo AWS

1. L'utente interagisce con una WebMap (nel mio esempio è una mappa leaflet che utilizza i dati cartografici di OpenStreetMap).

2. L'utente invia una POST ad un'API utilizzando

   1. le coordinate estreme della vista corrente della mappa
   2. lo zoom corrente della mappa
   3. un prompt contenente
   • un marker "inclusivo", marcando quindi la posizione come inclusa (a couple of float - latitude and longitude)
   • un marker "escludente", marcando quindi la posizione come esclusa (a couple of float - latitude and longitude)
   • a "include" rectangle (a couple of marker positions - north-east and south-west)

3. a causa del vincoli posti dai CORS è difficile inviare direttamente richieste a risorse remote su domini diversi da quello di origine: per evitare questo problema ho preparato una semplice funzione proxy su Cloudflare (questo sito funziona con le Cloudflare Pages) che inoltra la richiesta dell'utente all'API remota

4. Il API Gateway inoltra la richiesta al backend serverless

5. La API Lambda serverless elabora la richiesta:

   1. analizza la richiesta e in particolare traduce il prompt con le coordinate di latitudine/longitudine in uno di coordinate x/y mappate sull'origine dell'immagine
   2. scarica le tiles georeferenziate per poi unirle e ritagliarle
   3. crea un'istanza del modello MobileSam se non esistente utilizzando OnnxRuntime come runtime
   4. prepara il embedding delle immagini e...
   5. ...avvia il processo di inferenza
   6. trasforma il array di maschere di oggetti riconosciuti in un'unica immagine binaria quindi vettorializza la maschera binaria riconosciuta:
      1. innanzitutto converte la maschera in un GeoDataframe GeoPandas utilizzando rasterio.features.shapes e GeoDataFrame.from_features
      2. quindi esporta il nuovo Geodataframe in un geojson utilizzando GeoDataFrame.to_json

6. la funzione proxy Cloudflare elabora la risposta e la inoltra al frontend

7. il frontend estrae dalla risposta il geojson che sarà poi caricato all'interno della WebMap. Sono anche aggiunte alcune informazioni come la durata non relativistica della risposta

   

Per evitare abusi la webmap dedicata a questo progetto sul mio sito personale è sotto autenticazione (utilizzo auth0.com).

Architettura della demo basata su Fastapi

Questa variante del progetto funziona in maniera abbastanza simile a questa. Queste le differenze principali:

• opencv-python non è più fra le dipendenze di SamGIS dalla versione 1.5.1
• il backend salva e riutilizza gli embedding delle immagini per evitare sprechi di potenza di calcolo e velocizzare il processo di inferenza
• il frontend SPA (Single Page Application) è esposto direttamente dall'applicazione Fastapi

Frontend e backend quindi risiedono sullo stesso dominio. Non servirà più quindi un proxy (la demo su AWS usava una Page function di Cloudflare) per fare richieste ad API su un dominio diverso.

Inoltre, posso mantenere online questa demo usando HuggingFace gratuitamente, rimuovendo la necessità di us sistema di autenticazione.

AWS lambda, una soluzione serverless: alcuni pro...

• Può funzionare anche con immagini docker, molto utile nel caso di progetti complessi
• Integrazione abbastanza semplice con altri servizi AWS e sistemi di autenticazione di terze parti
• Servizio a consumo

...e alcuni svantaggi

• Configurazione non sempre facile (ho utilizzato Powertools for AWS Lambda (Python) per migliorare la configurazione del mio logger)
• Il modello serverless suggerito da AWS non sempre è la soluzione migliore
• Le istanze Arm graviton EC2 che eseguono AWS lambda sono notevolmente limitate (OnnxRuntime al momento non può essere eseguito su AWS lambda Arm e probabilmente non sarà mai supportato).

This project, composed by a SPA frontend and by a backend (samgis-be), is an attempt to perform machine learning image segmentation on geo-spatial data even without the use of dedicated graphics cards. I recently added the ability to start from natural language text prompts.

I wrote the backend adapting SAM Exporter with the aim to use the machine learning segment anything project for the purpose to improve polygons recognition in GIS web applications.

Starting from version 1.5.1 the backend integrates changes borrowed from sam_onnx_full_export, to support OnnxRuntime 1.17.x and later versions. Please note that on MacOS directly running the project from the command line suffers from memory leaks, making inference operations slower than normal. It's best therefore running the project inside a docker container, unless in case of development or debugging activities.

These are the project resource links:

• a public HuggingFace space demo
• the documentation and AWS lambda OpenAPI specs

Note that the HuggingFace space demo has its static frontend files under the /static folder.

Ask me for a user via linkedin if you would like to test the authenticated demo or an explanation about the code.

LISA and SamGIS

I also added support for image segmentation via natural language text prompts: here are the details about the SamGIS integration with LISA.

SamGIS also replaces SurferDTM

SurferDTM was an attempt to find stratovolcanoes within digital terrain models (DEM/DTM). As a new feature SamGIS now can now use also input DEM images (like the first image in this gallery):

Note that the "terrarium" source provider data encode the image as RGB, so the backend processes it to obtain the elevation data (like the second image in this gallery) using this formula (from the map tile provider page):

(red * 256) + green + (blue / 256) - 32768

I also added a custom elaboration step to create an intermediate RGB image composed by channels:

• RED - normalized DEM image
• GREEN - normalized 2d composed image by
  • normalized DEM image
  • slope
  • curvature
• BLUE - curvature

Segment Anything will finally do the inference on this rgb image.

{
   "bbox": {
         "ne": {"lat": 46.203706648934954, "lng": 9.401906739170105},
         "sw": {"lat": 46.12464369105346, "lng": 9.231103669101747}},
   "prompt": [
         {"id": 238, "type": "point", "data": {"lat": 46.158760519552146, "lng": 9.306795638666486}, "label": 1},
         {"id": 250, "type": "point", "data": {"lat": 46.152693546080975, "lng": 9.289288652508679}, "label": 0},
         {"id": 264, "type": "point", "data": {"lat": 46.16613515509541, "lng": 9.319840059725284}, "label": 0},
         {"id": 272, "type": "point", "data": {"lat": 46.161377438862836, "lng": 9.288087192674299}, "label": 0},
         {"id": 285, "type": "point", "data": {"lat": 46.174103408003454, "lng": 9.308340372739261}, "label": 0},
         {"id": 293, "type": "point", "data": {"lat": 46.17005996124035, "lng": 9.298042145587583}, "label": 0}
   ],
   "zoom": 13,
   "source_type": "nextzen.terrarium"
}

Project Architecture of AWS demo

1. The user interact with a WebMap (in my example it's a leaflet map that use OpenStreetMap map data).

2. The user send a POST request to an API using

   1. the current map extent
   2. the current map zoom
   3. a prompt array of objects; objects could be
      • an "include" marker position (a couple of float - latitude and longitude)
      • an "exclusionary" marker position (a couple of float - latitude and longitude)
      • a "include" rectangle (two latitude and longitude positions - north-east and south-west)

3. because of CORS constrain it's difficult to directly send requests to remote resources on different domains: to avoid this problems I prepared a simple Cloudflare proxy function that forward the user request to the remote API

4. The API Gateway proxies the request to the serverless backend

5. the serverless Lambda API elaborate the request:

   1. it parses the request and in particular translate the input latitude/longitude prompt into a x/y (pixel coordinates) one
   2. it downloads the geo-referenced tiles then merge and crop them
   3. it instantiates a MobileSam model instance if not already created using OnnxRuntime as runtime
   4. it prepares the image embedding and...
   5. ...it starts the image inference process
   6. it transforms the recognition masks into a single binary mask then it vectorizes the recognized binary mask:
      1. first it converts the mask into a GeoPandas GeoDataframe using rasterio.features.shapes and GeoDataFrame.from_features
      2. then it convert the new Geodataframe into a geojson using GeoDataFrame.to_json

6. the Cloudflare proxy function parses the response and forward it to the frontend

7. the frontend parse the geojson to load within the WebMap and shows some response info like the non-relativistic response duration time:

   

To avoid abuse the prompt input web map that I host on my personal site is under authentication (I use auth0.com).

Fastapi-based demo architecture

This project variant works almost as this. There are these differences:

• opencv-python is not anymore a SamGIS project dependency
• the server now saves and re-uses image embeddings to avoid resource waste and speed up the inference process
• SPA frontend now is integrated directly within the Fastapi backend

Frontend and backend now are on the same domain. Therefore there is no longer use for a proxy (the AWS demo used a Cloudflare Pages function) to make requests to APIs on a different domain.

Additionally, since I can host this Fastapi demo for free on HuggingFace, I don't need anymore an authentication system.

AWS lambda, a serverless solution: some pros...

• It can work also with docker images for complex or big projects (like this)
• Almost easy, working out-of-the-box integration with other AWS services and third-parts authentication systems
• Pay-as-you-go service

...and some cons

• Setup not always easy (I used Powertools for AWS Lambda (Python) to improve my logger setup)
• The serverless model suggested by AWS not always it's the best solution
• Arm graviton EC2 instances that run AWS lambda are greatly limited (OnnxRuntime at the moment cannot run on Arm AWS lambda and probably will never run).

Integrazione con SamGIS

Al momento ho gestisco queste attività di analisi d'immagine utilizzando SamGIS. Ecco due casi d'uso per effettuare instance segmentation in modo automatico dell'Etna utilizzando due diversi tiles providers (OpenStreetMap HOT) e (Nextzen /Terrario Mapzen).

OpenStreetMap HOT

Nextzen/Mapzen terrarium

Basi scientifiche del vecchio progetto (una specie di...)

Questo piccolo progetto prosegue idealmente il mio lavoro di tesi di laurea magistrale. Per portare questa idea al livello successivo (e per provare in prima persona alcune tecnologie interessanti) ho creato questo progetto fullstack. Fondamentalmente inizio estraendo il contorno di un'area geografica (per ora parto semplicemente dalla lista di coordinate di vulcani noti a livello mondiale). Utilizzo queste coordinate per preparare un raster DTM, poi elaborato in un'immagine RGB (pendenza - elevazione - curvatura) che sottopongo ad un modello di machine learning. L'output del modello di machine learning è una (o più) lista di coordinate che posso geo-referenziare e rappresentare in una webmap.

Ho basato questo lavoro su Mapzen Terrain Tiles perché questo set di dati contiene dati di elevazione sia terrestri che batimetrici.

Al momento ho sostituito lo stack tecnologico alla base di SurferDTM con SamGIS, offrendo prestazioni migliori ed essendo più facile da gestire.

Integration with SamGIS

Right now I solved these image segmentation tasks using SamGIS. Here two a use case for automatic instance segmentation of Etna volcano using two different tile providers (OpenStreetMap HOT) and (Nextzen/Mapzen terrarium).

OpenStreetMap HOT

Nextzen/Mapzen terrarium

Scientific basis of the old project (sort of...)

This little project ideally prosecute my Master Degree's work thesis. To bring this idea to the next level (and to try first-hand some cool technologies) I created this fullstack project. Basically I start extracting a geographic area polygon (right now I simply start from the list of volcanoes known worldwide). I use these coordinates to prepare a DTM raster, then elaborated in an RGB (slope - elevation - curvature) image that I submit to a machine learning instance detection. The machine learning model response it's one (or more) array(s) of coordinates points that I can georeference and show on my frontend map.

I have replaced the underlying technology stack of SurferDTM with SamGIS because it offers better performance and it's easier to manage.

Una camminata verso Fuentes (Colico)

Alcune foto vicino a Fuentes (Colico)

Foto scattate il 1 ottobre 2023.

A walk towards Fuentes (Colico)

Some photos near Fuentes (Colico)

Photos taken on 1 October 2023.

Tornando in Val Masino

Altre trentasei vedute della Val Masino

Foto scattate il 24 Settembre 2023.

Going back to Val Masino

Let's take again thirty-six views of Val Masino

Photos taken on 24 September 2023.

When I go hiking often I take photos of the landscape I cross. For this reason I try to prepare some gps tracks for my walks and excursions, so I started adding markers to show the position where I took the photos.

I display my photos using PhotoSwipe and I use Leaflet to handle geographical maps. From a technical point of view I display on the map:

• geojson for gps tracks of hiking
• for every photo there is a marker with a popup containing a thumbnail and a link to the corresponding photo gallery image

Also for every photo gallery page I add a PhotoSwipe gallery containing some custom ui html elements: an svg icon referring the photo marker within the map and a custom onClick() function.

These components can work together thanks to a global state handled by pinia. First I defined the pinia store:

// .vitepress/store/stores.ts

import { defineStore } from "pinia";

const mapStore = defineStore('map-store', {
    state: () => {
        return {
            closePopup: Boolean,
            markers: [],
            selectedPopupCoordinate: Array,
            selectedPopupId: Number,
            selectedPopupIdWithCoordinates: Number,
            selectedImageIndex: Number,
        }
    }
})

export { mapStore }

I use two Vue components: GalleryComponent.vue and MapComponent.vue.

How to open the correct photo within the photo gallery clicking on a marker popup

Every popup marker contains a link that, on click, patches the pinia state with the selected photo ID (and the corresponding marker ID). The tricky part was connecting this function to the a HTML popup element, so I created a wrapper function getPopup() that before creates the HTML elements with the correct onClick() function I already talked about (lines 17-23):

// MapComponent.vue

// define the pinia state store
if (inBrowser && localStore == null) {
    localStore = photoStore();
}
/* ... */

function getPopup(id, titleContent, urlthumb): HTMLDivElement {
  // manually build html elements to set global pinia state from here
  const title: HTMLSpanElement = document.createElement("span")
  title.innerHTML = `${titleContent}`

  const a: HTMLAnchorElement = document.createElement("a");
  a.id = `popup-a-${id}`
  // this action opens the selected photo within the photo gallery and close this marker popup
  a.onClick = function eventClick(event) {
    event.preventDefault()
    localStore.$patch({
      selectedImageIndex: id,
      closePopup: true
    })
  }
  a.appendChild(title)

  const div: HTMLDivElement = document.createElement("div");
  div.appendChild(a)
  return div
}

Of course the Vue component should contains also a way the read the updated store and here I use the selectedImageIndex variable to open the selected image within the photo gallery:

// GalleryComponent.vue

let localMapStore;
if (inBrowser && localMapStore == null) {
  localMapStore = mapStore();
  localMapStore.$subscribe((mutation, state) => {
    const {payload} = mutation;
    const {selectedImageIndex} = payload;
    // open the selected photo within the photo gallery
    if (selectedImageIndex != undefined) {
        handleGalleryOpen(selectedImageIndex)
    }
  })
}

/* ... */

const handleGalleryOpen = (index) => {
  // from https://github.com/hzpeng57/vue-preview-imgs/blob/master/packages/example/src/App.vue
  lightbox.loadAndOpen(parseInt(index, 10));
};

Going backwards: from a photo within the photo gallery to the corresponding popup marker

When a user clicks the link inside the popup marker to open the corresponding photo, the sequence of actions is simple: first clicking the popup link patches the pinia state, then the store instance uses the method .$subscribe({...}) to open the selected photo in the photo gallery. Easy.

The reverse process, however, is more complicated: the leaflet map can't show a marker if before it hasn't set the map view using the correct marker coordinates, but the photo gallery knows only about the current image index itself (lines 24-29):

onMounted(() => {
  const galleryDiv: HTMLElement | null = document.getElementById(`gallery-photo-${props.galleryID}`)
  const galleryChildren: HTMLCollection | undefined = galleryDiv?.children
  const dataSource = {
    gallery: galleryDiv,
    items: galleryChildren
  }
  const options = {
    gallery: `#gallery-photo-${props.galleryID}`,
    children: 'a',
    pswpModule: () => import('photoswipe'),
    dataSource: dataSource // fix missing gallery on first load with custom lightbox.loadAndOpen() action
  }
  if (lightbox != new PhotoSwipeLightbox({})) {
    lightbox = new PhotoSwipeLightbox(options);
    lightbox.on('uiRegister', function () {
      lightbox.pswp.ui.registerElement({
        name: 'location-button',
        order: 8,
        isButton: true,
        tagName: 'a',
        html: '<svg code ... />',
        // onClick function for the custom position button within GalleryComponent.vue, onMount() hook
        onClick: function (event, el, pswp) {
          localMapStore.$patch({
            selectedPopupIdFromGallery: parseInt(pswp.currSlide.index, 10)
          })
          pswp.close()
        }
      });
    });
    lightbox.init();
  }
})

Note on line 12: that's a workaround needed to avoid the gallery has missing content on the first load when using a custom lightbox.loadAndOpen() method.

Because of the missing marker coordinates during the former patch store action I added an intermediate step where I filter the markers I already put within the store to extract the selected marker coordinates:

// GalleryComponent.vue
import { LatLngTuple } from "leaflet";
// ...

let localMapStore;
if (inBrowser && localMapStore == null) {
  localMapStore = mapStore();
  localMapStore.$subscribe((mutation, state) => {
    const {payload} = mutation;
    const {selectedPopupIdFromGallery} = payload;
    // filter the markers to select the marker coordinates used to set the marker map view
    let {markers} = state;
    let selectedMarkers: [] = markers[props.galleryID]
    if (selectedPopupIdFromGallery != undefined && selectedMarkers != undefined) {
      // m.id: number type!
      let filteredMarker = selectedMarkers.find(m => m.id == selectedPopupIdFromGallery)
      const coordinate: LatLngTuple = filteredMarker.coordinate
      localMapStore.$patch({
        selectedPopupCoordinate: coordinate,
        selectedPopupIdWithCoordinates: filteredMarker.id
      })
    }
  })
}

Note that in this case the objects within the markers array contain at least id (a number variable) and coordinate (LatLngTuple type from leaflet). Next phase should use the store payload content (selectedPopupIdWithCoordinates and selectedPopupCoordinate) to set the current map view where the selected marker is and then to open his popup:

// MapComponent.vue
  const zoomValue = 18

  const popupContent = getPopup(/* ... */)
  let popup = L.popup(m.coordinate).setContent(popupContent)
  const marker = L.marker(coordinate, {/* ... */}).bindPopup(popup);
  // here add the current marker to the marker cluster instance...
  localMapStore.$subscribe((mutation, state) => {
    const {payload} = mutation;
    const {closePopup, selectedPopupIdWithCoordinates, selectedPopupCoordinate} = payload;
    if (selectedPopupIdWithCoordinates == m.idx && selectedPopupCoordinate) {
      // m.id: number type!
      map.setView(selectedPopupCoordinate, zoomValue)
      marker.openPopup()
    }
    if (closePopup) {
      marker.closePopup()
    }
  })
  // ...

And... that's the way you do it!

VitePress pre-renders the app in Node.js during the production build, using Vue's Server-Side Rendering (SSR) capabilities: this fact prevents using 'leaflet.markercluster' (or its wrapper module 'vue-leaflet-markercluster') within a vitepress project. Let's say we create this simple Leaflet map within a Vue component imported within a vitepress project:

<template>
  <div id="map">
    <l-map
      :zoom="9"
      :center="[45.1, 9.1]"
      :use-global-leaflet="true"
    >
      <l-tile-layer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" :attribution="attribution"/>
      <l-marker-cluster-group>
        <l-marker :lat-lng="[45.1, 9.1]"/>
        <l-marker :lat-lng="[45.2, 9.2]"/>
        <l-marker :lat-lng="[45.3, 9.3]"/>
      </l-marker-cluster-group>
    </l-map>
  </div>
</template>

<script setup lang="ts">
import {LMarker, LMap, LTileLayer} from "@vue-leaflet/vue-leaflet";
import L, {marker} from 'leaflet'

globalThis.L = L
import {LMarkerClusterGroup} from 'vue-leaflet-markercluster'
import {ref} from 'vue'

import 'leaflet/dist/leaflet.css'
import 'vue-leaflet-markercluster/dist/style.css'

const attribution = ref("openstreetmap contributors")
const prefix = ref("leaflet")
</script>

<style scoped>
#map {
  height: 50vh;
  width: 100%;
}
</style>

While running this code with yarn docs:dev or pnpm docs:dev (aliases of vitepress dev docs, see the vitepress documentation) it's fine, of course the leaflet.markercluster SSR requirements break the build step. Luckily it's possible to build the project using the import() syntax, commonly called dynamic import. There are different possible implementations (e.g. async components) but in this case I prefer using the classic JS syntax within the onBeforeMount() hook, then we can fix the broken component this way:

<template>
  <div id="map-photos"/>
</template>

<script setup lang="ts">
import "leaflet/dist/leaflet.css";
import "leaflet.markercluster/dist/MarkerCluster.css"
import "leaflet.markercluster/dist/MarkerCluster.Default.css"
import {onBeforeMount} from "vue";

onBeforeMount(async () => {
  const L = await import("leaflet")
  const {MarkerClusterGroup} = await import('leaflet.markercluster/dist/leaflet.markercluster')

  const map = L.map("map-photos") // div id
  map.setView([45.1, 9.1], 8)
  L.tileLayer("http://{s}.tile.osm.org/{z}/{x}/{y}.png").addTo(map);
  let mcluster = new MarkerClusterGroup()
  let marker1 = new L.Marker([45.1, 9.1])
  let marker2 = new L.Marker([45.2, 9.2])
  let marker3 = new L.Marker([45.3, 9.3])
  marker1.addTo(mcluster)
  marker2.addTo(mcluster)
  marker3.addTo(mcluster)
  mcluster.addTo(map)
})
</script>

<style scoped>
#map-photos {
  width: 100%;
  height: 60vh;
}
</style>

Note that onBeforeMount() must be async to make it work. Last but not least the package.json of this vitepress project contains these dependencies:

{
  "name": "vitepress-ssr-build",
  "version": "1.0.0",
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "pnpm i --frozen-lockfile && vitepress build docs",
    "docs:serve": "vitepress serve docs",
    "docs:preview": "vitepress preview docs --port 3000"
  },
  "license": "MIT",
  "type": "module",
  "dependencies": {
    "@vue-leaflet/vue-leaflet": "^0.10.1",
    "leaflet": "^1.9.4",
    "leaflet.markercluster": "^1.5.3",
    "vitepress": "^1.0.0-rc.10",
    "vue": "^3.3.4"
  },
  "devDependencies": {
    "@tsconfig/recommended": "^1.0.2",
    "@types/geojson": "^7946.0.10",
    "@types/leaflet": "^1.9.4",
    "@types/leaflet.markercluster": "^1.5.2"
  }
}

Quando vado a fare escursioni spesso scatto foto dei dintorni. Per questo motivo cerco di registrare il percorso delle mie passeggiate insieme ai segnalibri con la posizione delle foto.

Al momento uso Leaflet per gestire le mappe geografiche e PhotoSwipe per le gallerie fotografiche. Dal punto di vista tecnico visualizzo sulla mappa:

• i geojson contenenti le tracce gps delle escursioni
• per ogni foto i segnalibri con le coordinate delle foto a cui è connesso un popup contenente una thumbnail della foto ed un collegamento all'immagine nella photogallery corrispondente

Inoltre in questo caso personalizzo la galleria photoswipe aggiungendo alcuni elementi html custom dell'interfaccia grafica (un'icona SVG che rimanda al segnalibro della foto all'interno della mappa con una funzione onClick() custom).

Questi componenti possono lavorare insieme grazie ad uno stato globale gestito da pinia. Per prima cosa ho creato lo store contenente lo stato globale:

// .vitepress/store/stores.ts

import { defineStore } from "pinia";

const mapStore = defineStore('map-store', {
    state: () => {
        return {
            closePopup: Boolean,
            markers: [],
            selectedPopupCoordinate: Array,
            selectedPopupId: Number,
            selectedPopupIdWithCoordinates: Number,
            selectedImageIndex: Number,
        }
    }
})

export { mapStore }

Definiamo inoltre due componenti vue: GalleryComponent.vue e MapComponent.vue.

1. Come aprire la foto selezionata all'interno della galleria fotografica facendo clic sul popup del marker leaflet

Ogni popup leaflet contiene un collegamento che, al clic, aggiorna lo store usando l'ID della foto selezionata (ovvero l'ID del marker corrispondente). La parte difficile è stata connettere la funzione che aggiorna lo store al HTMLAnchorElement a contenuto nel popup. Per superare l'ostacolo ho creato una funzione wrapper getPopup() che prima crea gli elementi HTML necessari, fra cui anche l'elemento HTML a con il metodo custom onClick() di cui sopra (righe 17-23):

// MapComponent.vue

// define the pinia state store
if (inBrowser && localStore == null) {
    localStore = photoStore();
}
/* ... */

function getPopup(id, titleContent, urlthumb): HTMLDivElement {
  // manually build html elements to set global pinia state from here
  const title: HTMLSpanElement = document.createElement("span")
  title.innerHTML = `${titleContent}`

  const a: HTMLAnchorElement = document.createElement("a");
  a.id = `popup-a-${id}`
  // this action opens the selected photo within the photo gallery and close this marker popup
  a.onClick = function eventClick(event) {
    event.preventDefault()
    localStore.$patch({
      selectedImageIndex: id,
      closePopup: true
    })
  }
  a.appendChild(title)

  const div: HTMLDivElement = document.createElement("div");
  div.appendChild(a)
  return div
}

Ovviamente il componente Vue dovrebbe contenere anche un modo per leggere lo store aggiornato da cui estrarre la variabile selectedImageIndex con cui aprire poi l'immagine nella galleria fotografica:

// GalleryComponent.vue

let localMapStore;
if (inBrowser && localMapStore == null) {
  localMapStore = mapStore();
  localMapStore.$subscribe((mutation, state) => {
    const {payload} = mutation;
    const {selectedImageIndex} = payload;
    // open the selected photo within the photo gallery
    if (selectedImageIndex != undefined) {
        handleGalleryOpen(selectedImageIndex)
    }
  })
}

/* ... */

const handleGalleryOpen = (index) => {
  // from https://github.com/hzpeng57/vue-preview-imgs/blob/master/packages/example/src/App.vue
  lightbox.loadAndOpen(parseInt(index, 10));
};

2. Andando indietro: da una foto all'interno della galleria fotografica al corrispondente indicatore popup

Quando un utente fa clic sul collegamento all'interno del popup per aprire la foto corrispondente, la sequenza di azioni è semplice: prima facendo clic sul collegamento nel popup si aggiorna lo store pinia. In seguito l'istanza dello store con il metodo .$subscribe({...}) apre la foto selezionata all'interno della galleria fotografica. Facile.

Il processo inverso, però, è più complicato: la mappa leaflet non può aprire il popup senza aver preventivamente impostato la view corrispondente alle coordinate del marker selezionato. La galleria fotografica però ha soltanto il dato relativo al ID dell'immagine stessa attualmente aperta (righe 24-29):

onMounted(() => {
  const galleryDiv: HTMLElement | null = document.getElementById(`gallery-photo-${props.galleryID}`)
  const galleryChildren: HTMLCollection | undefined = galleryDiv?.children
  const dataSource = {
    gallery: galleryDiv,
    items: galleryChildren
  }
  const options = {
    gallery: `#gallery-photo-${props.galleryID}`,
    children: 'a',
    pswpModule: () => import('photoswipe'),
    dataSource: dataSource // fix missing gallery on first load with custom lightbox.loadAndOpen() action
  }
  if (lightbox != new PhotoSwipeLightbox({})) {
    lightbox = new PhotoSwipeLightbox(options);
    lightbox.on('uiRegister', function () {
      lightbox.pswp.ui.registerElement({
        name: 'location-button',
        order: 8,
        isButton: true,
        tagName: 'a',
        html: '<svg code ... />',
        // onClick function for the custom position button within GalleryComponent.vue, onMount() hook
        onClick: function (event, el, pswp) {
          localMapStore.$patch({
            selectedPopupIdFromGallery: parseInt(pswp.currSlide.index, 10)
          })
          pswp.close()
        }
      });
    });
    lightbox.init();
  }
})

Notare la riga 12: si tratta di un workaround necessario per evitare che il contenuto della galleria sia mancante al primo caricamento custom (in questo caso usando lightbox.loadAndOpen()) della galleria.

A causa delle coordinate mancanti del marker nella fase precedente ho aggiunto un passaggio intermedio si filtrano i marker estratti dallo store per ricavare le coordinate del marker selezionato:

// GalleryComponent.vue
import { LatLngTuple } from "leaflet";
// ...

let localMapStore;
if (inBrowser && localMapStore == null) {
  localMapStore = mapStore();
  localMapStore.$subscribe((mutation, state) => {
    const {payload} = mutation;
    const {selectedPopupIdFromGallery} = payload;
    // filter the markers to select the marker coordinates used to set the marker map view
    let {markers} = state;
    let selectedMarkers: [] = markers[props.galleryID]
    if (selectedPopupIdFromGallery != undefined && selectedMarkers != undefined) {
      // m.id: number type!
      let filteredMarker = selectedMarkers.find(m => m.id == selectedPopupIdFromGallery)
      const coordinate: LatLngTuple = filteredMarker.coordinate
      localMapStore.$patch({
        selectedPopupCoordinate: coordinate,
        selectedPopupIdWithCoordinates: filteredMarker.id
      })
    }
  })
}

Si noti che in questo caso gli oggetti dentro all'array markers conterranno almeno id (tipo numero) e coordinate (LatLngTuple dalla libreria leaflet). La fase successiva usa il contenuto del payload dello store (selectedPopupIdWithCoordinates e selectedPopupCoordinate in particolare) per impostare la visualizzazione corrente della mappa in cui si trova il segnalibro selezionato ed aprirne quindi finalmente il popup:

// MapComponent.vue
  const zoomValue = 18

  const popupContent = getPopup(/* ... */)
  let popup = L.popup(m.coordinate).setContent(popupContent)
  const marker = L.marker(coordinate, {/* ... */}).bindPopup(popup);
  // here add the current marker to the marker cluster instance...
  localMapStore.$subscribe((mutation, state) => {
    const {payload} = mutation;
    const {closePopup, selectedPopupIdWithCoordinates, selectedPopupCoordinate} = payload;
    if (selectedPopupIdWithCoordinates == m.idx && selectedPopupCoordinate) {
      // m.id: number type!
      map.setView(selectedPopupCoordinate, zoomValue)
      marker.openPopup()
    }
    if (closePopup) {
      marker.closePopup()
    }
  })
  // ...

E... that's the way you do it!

VitePress esegue il pre-rendering dell'app in Node.js durante la build di produzione, utilizzando le funzionalità di rendering lato server (SSR) di Vue: questo fatto impedisce di usare leaflet.markercluster all'interno di un progetto vitepress. Supponiamo di creare questa semplice mappa leaflet all'interno di un componente vue a sua volta utilizzato in un progetto vitepress:

<template>
  <div id="map">
    <l-map
      :zoom="9"
      :center="[45.1, 9.1]"
      :use-global-leaflet="true"
    >
      <l-tile-layer url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png" :attribution="attribution"/>
      <l-marker-cluster-group>
        <l-marker :lat-lng="[45.1, 9.1]"/>
        <l-marker :lat-lng="[45.2, 9.2]"/>
        <l-marker :lat-lng="[45.3, 9.3]"/>
      </l-marker-cluster-group>
    </l-map>
  </div>
</template>

<script setup lang="ts">
import {LMarker, LMap, LTileLayer} from "@vue-leaflet/vue-leaflet";
import L, {marker} from 'leaflet'

globalThis.L = L
import {LMarkerClusterGroup} from 'vue-leaflet-markercluster'
import {ref} from 'vue'

import 'leaflet/dist/leaflet.css'
import 'vue-leaflet-markercluster/dist/style.css'

const attribution = ref("openstreetmap contributors")
const prefix = ref("leaflet")
</script>

<style scoped>
#map {
  height: 50vh;
  width: 100%;
}
</style>

Mentre yarn docs:dev o pnpm docs:dev (alias di vitepress dev docs, si veda la documentazione vitepress) eseguono con successo il codice qui sopra, la fase di build fallisce a causa appunto dell'utilizzo di SSR da parte di leaflet.markercluster. Fortunatamente è possibile evitare il problema utilizzando la sintassi import(), comunemente definitita "import dinamico". Esistono diverse implementazioni possibili (ad es. async components) ma in questo caso preferisco utilizzare la classica sintassi javascript all'interno dell'hook onBeforeMount(). Si può quindi eliminare il malfunzionamento in questo modo:

<template>
  <div id="map-photos"/>
</template>

<script setup lang="ts">
import "leaflet/dist/leaflet.css";
import "leaflet.markercluster/dist/MarkerCluster.css"
import "leaflet.markercluster/dist/MarkerCluster.Default.css"
import {onBeforeMount} from "vue";

onBeforeMount(async () => {
  const L = await import("leaflet")
  const {MarkerClusterGroup} = await import('leaflet.markercluster/dist/leaflet.markercluster')

  const map = L.map("map-photos") // div id
  map.setView([45.1, 9.1], 8)
  L.tileLayer("http://{s}.tile.osm.org/{z}/{x}/{y}.png").addTo(map);
  let mcluster = new MarkerClusterGroup()
  let marker1 = new L.Marker([45.1, 9.1])
  let marker2 = new L.Marker([45.2, 9.2])
  let marker3 = new L.Marker([45.3, 9.3])
  marker1.addTo(mcluster)
  marker2.addTo(mcluster)
  marker3.addTo(mcluster)
  mcluster.addTo(map)
})
</script>

<style scoped>
#map-photos {
  width: 100%;
  height: 60vh;
}
</style>

Si noti che onBeforeMount() deve esser asincrono per funzionare. Ultimo ma non per importanza il package.json di questo progetto vitepress minimale deve contenere queste dipendenze:

{
  "name": "vitepress-ssr-build",
  "version": "1.0.0",
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "pnpm i --frozen-lockfile && vitepress build docs",
    "docs:serve": "vitepress serve docs",
    "docs:preview": "vitepress preview docs --port 3000"
  },
  "license": "MIT",
  "type": "module",
  "dependencies": {
    "@vue-leaflet/vue-leaflet": "^0.10.1",
    "leaflet": "^1.9.4",
    "leaflet.markercluster": "^1.5.3",
    "vitepress": "^1.0.0-rc.10",
    "vue": "^3.3.4"
  },
  "devDependencies": {
    "@tsconfig/recommended": "^1.0.2",
    "@types/geojson": "^7946.0.10",
    "@types/leaflet": "^1.9.4",
    "@types/leaflet.markercluster": "^1.5.2"
  }
}

Una passeggiata nei dintorni di Bormio

Trentadue viste di Bormio e dintorni

Foto scattate il 26 agosto 2023.

A walk around Bormio

Thirty-two views of Bormio and surroundings

Photos taken on 26 August 2023.

I started from the twentyseconds LaTeX theme because I think a LaTeX CV looks more professional. It's also possible to do things like this:

I like the two-column layout but not the left column created outside the document. Because of this I should set the dimensions of the second column exactly like those of the frame containing the text, making the use of LaTeX useless.

To replicate this two-column configuration I thought to use this clever solution based on the tcolorbox package.

First of all I created this basic LaTeX document:

\ProvidesClass{twentyonesecondcv}[2017/01/08 CV class]
\documentclass{article}
\usepackage{blindtext}
\usepackage{xcolor}
\usepackage{geometry}
\usepackage[most]{tcolorbox}
\geometry{margin=0pt}

\definecolor{gray}{HTML}{4D4D4D}
\definecolor{sidecolor}{HTML}{E7E7E7}
\definecolor{mainblue}{HTML}{0E5484}
\definecolor{maingray}{HTML}{B9B9B9}
\newtcolorbox{bgbox}[1][]{nobeforeafter,leftright skip=0pt,boxrule=0pt,enhanced jigsaw,sharp corners,#1}

\newcommand{\sidesection}[1]{
    \noindent
    \begin{bgbox}[height=\paperheight,colback=sidecolor,width=0.33\textwidth]
    #1
    \end{bgbox}%
}
\newcommand{\mainsection}[1]{%
    \noindent
    \begin{bgbox}[height=\paperheight,colback=white,width=0.67\textwidth]
    #1
    \end{bgbox}%
}

\documentclass[letterpaper]{twentyonesecondcv} % a4paper for A4

\begin{document}
\noindent
\sidesection{col 1, pag 1:: \lipsum[1-3]}
\mainsection{col 2, pag 1:: \textit{\lipsum[1-5]}}
\newpage

\noindent
\sidesection{col 1, pag2:: \lipsum[3-5]}
\mainsection{col 2, pag2:: \textit{\lipsum[3-7]}}
\end{document}

You can notice that this example is already on two pages: it's ok to keep your CV simple and quick to read, but what if you have a long list of experiences to show?

Of course LaTeX is good because the markup engine should keep you free to think about your content, not concentrating on handling manual placements of borders, paragraph positions and so on. My biggest problem about this was filling empty space: commands like \vfill aren't working within newtcolorbox because the box has no fixed height.

Luckily (should be from version 3.70) it's possible to change this behavior; for this you need the options

• height=<value>
• text fill

As already said, the box can't use \vfill because initially it hasn't a fixed height, so these options are changing that. I use height=\heigthpage because my boxes' height are equal to the entire page height.

Last precaution is to avoid commands enforcing fixed value settings like the tikzpicture one used within the custom command \makeheaderprofile.

For some reason instead the custom commands used to create the skill sections (\skills and \skillstext) work fine.

Finally here is the result and the GitHub repository!

I published this LaTeX template on this Overleaf page.

Updates

2024-06-26

• Add LICENSE file
• add alternative commands to create the side footer text

2024-01-24

• pull request from giocic2: fixed unwanted bfseries redefinition

2024-01-04

• fixed wrong \cvlinkedin command

2023-12-31

Added options to transform address and skype rows into urls

2023-09-01

• now it's possible to add an arbitrary number of skill bar sections with custom section titles, custom legends and custom skill values (see \customskills command)
• improved clarity of \skills command
• added some explanations about header and info profile sections
• renamed \cvdate to \cvbirthdate, changed its icon to faCalendar
• accepted a pull request from JeromeHen

2023-05-15

I added some options about:

• a way to hide the picture and display only the name / surname and job description row
• custom side sections
• removed a broken command (\skillstext)

Ho iniziato dal tema LaTeX di twentyseconds perché penso che un CV in LaTeX sembri più professionale. E' anche possibile fare cose come questa:

Mi piace il layout a due colonne ma non la colonna di sinistra creata all'esterno del documento (fatto che imporrebbe di scrivere il testo nella colonna di sinistra specificando esattamente le dimensioni del frame contenente il testo, rendendo di fatto inutile l'utilizzo di LaTeX). Per replicare questa configurazione a due colonne ho pensato di usare questa soluzione basata sul pacchetto tcolorbox.

Ho iniziato creando questa configurazione LaTeX di base:

\ProvidesClass{twentyonesecondcv}[2017/01/08 CV class]
\documentclass{article}
\usepackage{blindtext}
\usepackage{xcolor}
\usepackage{geometry}
\usepackage[most]{tcolorbox}
\geometry{margin=0pt}

\definecolor{gray}{HTML}{4D4D4D}
\definecolor{sidecolor}{HTML}{E7E7E7}
\definecolor{mainblue}{HTML}{0E5484}
\definecolor{maingray}{HTML}{B9B9B9}
\newtcolorbox{bgbox}[1][]{nobeforeafter,leftright skip=0pt,boxrule=0pt,enhanced jigsaw,sharp corners,#1}

\newcommand{\sidesection}[1]{
    \noindent
    \begin{bgbox}[height=\paperheight,colback=sidecolor,width=0.33\textwidth]
    #1
    \end{bgbox}%
}
\newcommand{\mainsection}[1]{%
    \noindent
    \begin{bgbox}[height=\paperheight,colback=white,width=0.67\textwidth]
    #1
    \end{bgbox}%
}

\documentclass[letterpaper]{twentyonesecondcv} % a4paper for A4

\begin{document}
\noindent
\sidesection{col 1, pag 1:: \lipsum[1-3]}
\mainsection{col 2, pag 1:: \textit{\lipsum[1-5]}}
\newpage

\noindent
\sidesection{col 1, pag2:: \lipsum[3-5]}
\mainsection{col 2, pag2:: \textit{\lipsum[3-7]}}
\end{document}

Si può notare che l'esempio è già su due pagine: va bene mantenere il CV semplice e facile da leggere, ma cosa fare con una lista di esperienze lavorative da mostrare più lunga di una pagina?

Latex è vantaggioso da usare perché permette di pensare al solo contenuto testuale, senza sprecare tempo con l'impaginazione. Il mio più grande problema era riempire l'eventuale spazio vuoto fra l'ultimo paragrafo ed il fondo della colonna: comandi come \vfill non funzionano all'interno di newtcolorbox perché il frame non ha un'altezza fissa.

Fortunatamente (dovrebbe essere dalla versione 3.70 di newtcolorbox) è possibile modificare questo comportamento; per questo serviranno le opzioni

• height=<value>
• text fill

Come già detto, il frame non può usare \vfill perché inizialmente non ha un'altezza fissa. Per imporre l'altezza del contenitore del testo uguale all'altezza dell'intera pagina serve height=\heigthpage.

L'ultima precauzione è evitare comandi che impongano valori fissi come quello tikzpicture usato all'interno del comando personalizzato \makeheaderprofile.

Per qualche ragione invece i comandi personalizzati usati per creare le sezioni delle abilità (\skills e \skillstext) funzionano bene.

Finalmente qui il risultato ed il repository GitHub!

Ho pubblicato il template LaTeX di esempio qui su Overleaf.

Updates

2024-06-26

• Aggiunto file con la LICENSE
• aggiunti comandi alternativi per creare il testo nel side footer

2024-01-04

• fixed wrong \cvlinkedin command

• pull request da giocic2: corretta la definizione di bfseries

04-01-2023

• corretto il comando \cvlinkedin

31-12-2023

Aggiunte opzioni per trasformare indirizzi Skype in URL

01-09-2023

• ora è possibile aggiungere un numero arbitrario di sezioni della barra delle skill con titoli di sezione personalizzabili, legende e skill personalizzabili (vedi comando \customskills)
• migliorata la chiarezza del comando \skills
• aggiunte alcune spiegazioni sulle sezioni dell'intestazione e del profilo informativo
• rinominato \cvdate in \cvbirthdate, cambiata la sua icona in faCalendar
• accettato una pull request da JeromeHen

2023-05-15

Aggiunte alcune opzioni:

• un modo per nascondere l'immagine e visualizzare solo la riga con nome/cognome ed descrizione della mansione lavorativa
• sezioni laterali personalizzabili
• rimosso un comando non funzionante (\skillstext)

Ho iniziato dal tema LaTeX di twentyseconds perché penso che un CV in LaTeX sembri più professionale. E' anche possibile fare cose come questa:

Mi piace il layout a due colonne ma non la colonna di sinistra creata all'esterno del documento (fatto che imporrebbe di scrivere il testo nella colonna di sinistra specificando esattamente le dimensioni del frame contenente il testo, rendendo di fatto inutile l'utilizzo di LaTeX). Per replicare questa configurazione a due colonne ho pensato di usare questa soluzione basata sul pacchetto tcolorbox.

Ho iniziato creando questa configurazione LaTeX di base:

\ProvidesClass{twentyonesecondcv}[2017/01/08 CV class]
\documentclass{article}
\usepackage{blindtext}
\usepackage{xcolor}
\usepackage{geometry}
\usepackage[most]{tcolorbox}
\geometry{margin=0pt}

\definecolor{gray}{HTML}{4D4D4D}
\definecolor{sidecolor}{HTML}{E7E7E7}
\definecolor{mainblue}{HTML}{0E5484}
\definecolor{maingray}{HTML}{B9B9B9}
\newtcolorbox{bgbox}[1][]{nobeforeafter,leftright skip=0pt,boxrule=0pt,enhanced jigsaw,sharp corners,#1}

\newcommand{\sidesection}[1]{
    \noindent
    \begin{bgbox}[height=\paperheight,colback=sidecolor,width=0.33\textwidth]
    #1
    \end{bgbox}%
}
\newcommand{\mainsection}[1]{%
    \noindent
    \begin{bgbox}[height=\paperheight,colback=white,width=0.67\textwidth]
    #1
    \end{bgbox}%
}

\documentclass[letterpaper]{twentyonesecondcv} % a4paper for A4

\begin{document}
\noindent
\sidesection{col 1, pag 1:: \lipsum[1-3]}
\mainsection{col 2, pag 1:: \textit{\lipsum[1-5]}}
\newpage

\noindent
\sidesection{col 1, pag2:: \lipsum[3-5]}
\mainsection{col 2, pag2:: \textit{\lipsum[3-7]}}
\end{document}

Si può notare che l'esempio è già su due pagine: va bene mantenere il CV semplice e facile da leggere, ma cosa fare con una lista di esperienze lavorative da mostrare più lunga di una pagina?

Latex è vantaggioso da usare perché permette di pensare al solo contenuto testuale, senza sprecare tempo con l'impaginazione. Il mio più grande problema era riempire l'eventuale spazio vuoto fra l'ultimo paragrafo ed il fondo della colonna: comandi come \vfill non funzionano all'interno di newtcolorbox perché il frame non ha un'altezza fissa.

Fortunatamente (dovrebbe essere dalla versione 3.70 di newtcolorbox) è possibile modificare questo comportamento; per questo serviranno le opzioni

• height=<value>
• text fill

Come già detto, il frame non può usare \vfill perché inizialmente non ha un'altezza fissa. Per imporre l'altezza del contenitore del testo uguale all'altezza dell'intera pagina serve height=\heigthpage.

L'ultima precauzione è evitare comandi che impongano valori fissi come quello tikzpicture usato all'interno del comando personalizzato \makeheaderprofile.

Per qualche ragione invece i comandi personalizzati usati per creare le sezioni delle abilità (\skills e \skillstext) funzionano bene.

Finalmente qui il risultato ed il repository GitHub!

Ho pubblicato il template LaTeX di esempio qui su Overleaf.

Updates

2024-06-26

• Aggiunto file con la LICENSE
• aggiunti comandi alternativi per creare il testo nel side footer

2024-01-04

• fixed wrong \cvlinkedin command

• pull request da giocic2: corretta la definizione di bfseries

04-01-2023

• corretto il comando \cvlinkedin

31-12-2023

Aggiunte opzioni per trasformare indirizzi Skype in URL

01-09-2023

• ora è possibile aggiungere un numero arbitrario di sezioni della barra delle skill con titoli di sezione personalizzabili, legende e skill personalizzabili (vedi comando \customskills)
• migliorata la chiarezza del comando \skills
• aggiunte alcune spiegazioni sulle sezioni dell'intestazione e del profilo informativo
• rinominato \cvdate in \cvbirthdate, cambiata la sua icona in faCalendar
• accettato una pull request da JeromeHen

2023-05-15

Aggiunte alcune opzioni:

• un modo per nascondere l'immagine e visualizzare solo la riga con nome/cognome ed descrizione della mansione lavorativa
• sezioni laterali personalizzabili
• rimosso un comando non funzionante (\skillstext)

I started from the twentyseconds LaTeX theme because I think a LaTeX CV looks more professional. It's also possible to do things like this:

I like the two-column layout but not the left column created outside the document. Because of this I should set the dimensions of the second column exactly like those of the frame containing the text, making the use of LaTeX useless.

To replicate this two-column configuration I thought to use this clever solution based on the tcolorbox package.

First of all I created this basic LaTeX document:

\ProvidesClass{twentyonesecondcv}[2017/01/08 CV class]
\documentclass{article}
\usepackage{blindtext}
\usepackage{xcolor}
\usepackage{geometry}
\usepackage[most]{tcolorbox}
\geometry{margin=0pt}

\definecolor{gray}{HTML}{4D4D4D}
\definecolor{sidecolor}{HTML}{E7E7E7}
\definecolor{mainblue}{HTML}{0E5484}
\definecolor{maingray}{HTML}{B9B9B9}
\newtcolorbox{bgbox}[1][]{nobeforeafter,leftright skip=0pt,boxrule=0pt,enhanced jigsaw,sharp corners,#1}

\newcommand{\sidesection}[1]{
    \noindent
    \begin{bgbox}[height=\paperheight,colback=sidecolor,width=0.33\textwidth]
    #1
    \end{bgbox}%
}
\newcommand{\mainsection}[1]{%
    \noindent
    \begin{bgbox}[height=\paperheight,colback=white,width=0.67\textwidth]
    #1
    \end{bgbox}%
}

\documentclass[letterpaper]{twentyonesecondcv} % a4paper for A4

\begin{document}
\noindent
\sidesection{col 1, pag 1:: \lipsum[1-3]}
\mainsection{col 2, pag 1:: \textit{\lipsum[1-5]}}
\newpage

\noindent
\sidesection{col 1, pag2:: \lipsum[3-5]}
\mainsection{col 2, pag2:: \textit{\lipsum[3-7]}}
\end{document}

You can notice that this example is already on two pages: it's ok to keep your CV simple and quick to read, but what if you have a long list of experiences to show?

Of course LaTeX is good because the markup engine should keep you free to think about your content, not concentrating on handling manual placements of borders, paragraph positions and so on. My biggest problem about this was filling empty space: commands like \vfill aren't working within newtcolorbox because the box has no fixed height.

Luckily (should be from version 3.70) it's possible to change this behavior; for this you need the options

• height=<value>
• text fill

As already said, the box can't use \vfill because initially it hasn't a fixed height, so these options are changing that. I use height=\heigthpage because my boxes' height are equal to the entire page height.

Last precaution is to avoid commands enforcing fixed value settings like the tikzpicture one used within the custom command \makeheaderprofile.

For some reason instead the custom commands used to create the skill sections (\skills and \skillstext) work fine.

Finally here is the result and the GitHub repository!

I published this LaTeX template on this Overleaf page.

Updates

2024-06-26

• Add LICENSE file
• add alternative commands to create the side footer text

2024-01-24

• pull request from giocic2: fixed unwanted bfseries redefinition

2024-01-04

• fixed wrong \cvlinkedin command

2023-12-31

Added options to transform address and skype rows into urls

2023-09-01

• now it's possible to add an arbitrary number of skill bar sections with custom section titles, custom legends and custom skill values (see \customskills command)
• improved clarity of \skills command
• added some explanations about header and info profile sections
• renamed \cvdate to \cvbirthdate, changed its icon to faCalendar
• accepted a pull request from JeromeHen

2023-05-15

I added some options about:

• a way to hide the picture and display only the name / surname and job description row
• custom side sections
• removed a broken command (\skillstext)

Una camminata in Val Masino

Trentasei vedute della Val Masino

Foto scattate il 23 Ottobre 2022.

A Walk in Val Masino

Thirty-six views of Val Masino

Photos taken on 23 October 2022.