AITracer by LAD: digitalizzazione di raster assistita dall’intelligenza artificiale in QGIS

Siamo lieti di presentare AITracer by LAD, un plugin per QGIS 4 che porta l’intelligenza artificiale direttamente nel flusso di lavoro della digitalizzazione raster in archeologia. Sviluppato dal Laboratorio di Archeologia Digitale (LAD) della Sapienza, AITracer consente di vettorializzare qualsiasi feature visibile su un layer raster georiferito — fotografie aeree, ortofoto da drone, planimetrie scansionate, rilievi fotogrammetrici — con un semplice clic del mouse.

Il plugin è rilasciato con licenza GNU GPL 3 ed è disponibile su GitHub:
🔗 https://github.com/lad-sapienza/ai-tracer

---

Il problema: la digitalizzazione manuale è lenta

Chi lavora quotidianamente con dati raster in ambito archeologico conosce bene il tempo che richiede la vettorializzazione manuale: tracciare a mano i contorni di strutture murarie, buche di palo, tagli stratigrafici o aree di frammenti ceramici su un’ortofoto ad alta risoluzione è un’operazione precisa ma estremamente laboriosa. I risultati dipendono molto dall’esperienza e dalla concentrazione dell’operatore, e i tempi si moltiplicano rapidamente quando le geometrie da digitalizzare sono decine o centinaia.

AITracer non elimina il giudizio dell’archeologo — che rimane sempre l’interprete — ma accelera radicalmente la fase meccanica del tracciamento, lasciando all’operatore il controllo pieno sul risultato.

---

Come funziona: SAM2 al servizio dell’archeologia

AITracer si basa su SAM2 (Segment Anything Model 2), il modello di segmentazione di immagini sviluppato da Meta FAIR e rilasciato open source. SAM2 è in grado di identificare e delimitare oggetti all’interno di un’immagine a partire da semplici indicazioni puntuali — i cosiddetti prompt — senza essere stato addestrato specificamente su immagini archeologiche.

Il flusso di lavoro è il seguente:

1. Si carica un layer raster georiferito in QGIS e si imposta lo zoom sull’area di interesse.
2. Si attiva il plugin tramite il pannello AITracer by LAD e si clicca sull’oggetto da digitalizzare.
3. SAM2 analizza la porzione di canvas visibile e restituisce in pochi istanti il contorno della feature, visualizzato come poligono di anteprima verde direttamente sulla mappa.
4. Si accetta il poligono (tasto Invio) oppure si affina il risultato con clic aggiuntivi prima di accettarlo.

Il modello viene eseguito localmente, sul proprio computer, senza inviare alcun dato a servizi esterni.

---

Il pannello di controllo

Una volta installato, il plugin aggiunge un pannello laterale alla finestra di QGIS.

Il pannello AITracer by LAD con il pulsante di attivazione, il cursore di semplificazione, i pulsanti Accetta e Annulla e i collegamenti a GitHub e alla documentazione.

---

Prompt positivi e negativi

Il cuore del sistema è l’interazione iterativa con il modello tramite prompt:

• Clic sinistro — prompt positivo: indica al modello un punto che deve essere incluso nel poligono.
• Clic destro — prompt negativo: indica un punto da escludere, utile per affinare il contorno quando il modello include aree non desiderate.

Ogni clic aggiuntivo raffina la segmentazione senza ricalcolare l’intera analisi dell’immagine, grazie a una cache della codifica dell’immagine che il backend mantiene per tutta la durata della sessione.

Dopo il primo clic sinistro sull’ortofoto, SAM2 restituisce quasi immediatamente un’anteprima del poligono (in verde) sovrapposta al layer raster.

---

Aggiunta di prompt negativi (clic destro) per escludere aree adiacenti erroneamente incluse nella segmentazione iniziale. Il poligono di anteprima si aggiorna in tempo reale.

---

Semplificazione geometrica in tempo reale

Le maschere prodotte da SAM2 possono contenere un numero molto elevato di vertici. AITracer integra un cursore di semplificazione Douglas-Peucker che permette di controllare la densità dei vertici del poligono finale prima di accettarlo, con passi di 0,01 unità mappa e un range da 0 (nessuna semplificazione) a 0,50.

Confronto tra il poligono con semplificazione a 0 (sinistra, molti vertici) e con semplificazione a 0,15 (destra, contorno semplificato ma fedele alla forma originale).

---

Annulla l’ultimo punto

Se un clic è stato piazzato nel punto sbagliato, non è necessario annullare l’intera sessione. Il tasto Ctrl+Z rimuove l’ultimo punto inserito — positivo o negativo — e ricalcola immediatamente la segmentazione con i punti rimanenti. È possibile tornare indietro quanto si vuole, fino ad azzerare tutti i prompt.

---

Accettare e salvare

Una volta soddisfatti del contorno, si preme Invio (o il pulsante Accetta nel pannello). Il poligono viene automaticamente aggiunto a un layer temporaneo in memoria chiamato AITracer, creato dal plugin con stile arancione semitrasparente. Il layer è completamente integrabile con il progetto QGIS e può essere esportato in qualsiasi formato vettoriale.

La feature accettata appare nel layer AITracer (in arancione semitrasparente) sovrapposto al layer raster di partenza. È possibile continuare a digitalizzare nuove feature senza interruzioni.

---

Scegliere il layer di destinazione

Di default, i poligoni accettati vengono inseriti in un layer temporaneo in memoria chiamato AITracer. Dal pannello è però possibile scegliere qualsiasi layer vettoriale poligonale già presente nel progetto come destinazione, tramite un menù a tendina che si aggiorna automaticamente. Alla prima accettazione, il menù viene impostato sul layer AITracer appena creato, così i clic successivi vi confluiscono senza dover selezionare nulla.

---

Ogni feature accettata registra automaticamente tre attributi:

Campo	Contenuto
fid	Identificativo progressivo automatico
timestamp	Data e ora di accettazione (ISO 8601)
raster	Nome del layer raster sorgente

La tabella degli attributi del layer AITracer con i campi fid, timestamp e raster compilati automaticamente per ciascuna feature accettata.

---

Prima installazione: tutto automatico

Il plugin gestisce autonomamente la propria infrastruttura computazionale. Al primo avvio:

1. crea un ambiente virtuale Python in ~/.aitracer/venv;
2. installa le dipendenze necessarie (FastAPI, PyTorch, SAM2, OpenCV);
3. scarica i pesi del modello SAM2-tiny (~40 MB).

Un dialogo di avanzamento informa l’utente in ogni fase. Le attivazioni successive richiedono pochi secondi.

---

Installazione del plugin

AITracer è disponibile sul repository ufficiale dei plugin di QGIS: plugins.qgis.org/plugins/aitracer. Questo rende l’installazione e l’aggiornamento del plugin estremamente semplici, con due modalità a disposizione.

Metodo 1 (consigliato): direttamente da QGIS

1. In QGIS, aprire Plugin → Gestisci e installa plugin.
2. Nelle Impostazioni, spuntare l’opzione Mostra anche i plugin sperimentali (AITracer è attualmente classificato come sperimentale).
3. Nella scheda Tutti, cercare AITracer e cliccare Installa plugin.

Con questo metodo, QGIS notificherà automaticamente la disponibilità di nuove versioni.

Metodo 2: download manuale dal repository

In alternativa, è possibile scaricare il pacchetto ZIP direttamente da plugins.qgis.org/plugins/aitracer tramite browser web e installarlo in QGIS con Plugin → Gestisci e installa plugin → Installa da ZIP.

Metodo 3: dalle release su GitHub

Per chi vuole testare versioni specifiche o pre-release, i pacchetti aitracer-vX.Y.Z.zip sono sempre disponibili anche dalla pagina delle Release su GitHub.

È richiesto QGIS 4.0. Il runtime Python necessario viene scaricato e installato automaticamente dal plugin al primo avvio tramite python-build-standalone: non è richiesta alcuna installazione manuale di Python.

La pagina di AITracer sul repository ufficiale dei plugin di QGIS.

Il gestore dei plugin di QGIS con AITracer trovato nel repository ufficiale, pronto per l’installazione.

---

Note importanti sull’uso: AITracer non legge i file raster, ma cattura lo schermo

AITracer usa lo schermo, non il file raster: ecco perché è importante saperlo

AITracer cattura uno screenshot della canvas di QGIS nel momento in cui si fa clic. Non legge i dati raster originali. Si tratta di una scelta progettuale precisa: mantiene il consumo di memoria basso e la segmentazione rapida anche su hardware modesto. IN questo modo nessun file da diversi gigabyte deve essere decodificato o caricato in RAM.

Questa scelta ha tre conseguenze pratiche che è importante conoscere prima di iniziare a digitalizzare:

• La risoluzione dipende dal livello di zoom. Se si è molto distanziati, ogni pixel dello schermo rappresenta un’area geografica ampia e i bordi del poligono risulteranno approssimativi. Ingrandire fino a far riempire il feature alla maggior parte della canvas permette di ottenere il risultato più preciso.
• Il feature deve essere completamente visibile. Qualsiasi parte di un oggetto che si estende oltre il bordo del canvas è semplicemente assente dallo screenshot. Se un muro, un confine di parcella o qualsiasi altra forma esce dallo schermo, solo la porzione visibile verrà inclusa nel poligono. Prima di fare clic, spostare e ingrandire la vista in modo che l’intero feature sia visibile.
• La canvas si blocca durante la sessione: questo è una scelta voluta. Dopo il primo clic, l’estensione del canvas viene congelata fino all’accettazione o all’annullamento. Spostare o ingrandire la vista durante la sessione invaliderebbe la corrispondenza tra coordinate pixel e coordinate geografiche, producendo geometrie errate. Il blocco viene rimosso nel momento in cui si preme Invio o Esc.

Suggerimento pratico: prima di attivare lo strumento, ingrandire la vista sul feature da digitalizzare lasciando un piccolo margine intorno, e assicurarsi che il raster di interesse sia l’unico layer visibile. Quindi attivare, fare clic, raffinare e accettare.

---

Una nota sul metodo: pair programming con l’IA

Questo plugin nasce anche come esperimento metodologico. L’intero processo di progettazione e sviluppo — dall’architettura del sistema alle singole funzioni Python, dalla gestione del backend alla UI del pannello — è stato condotto in stretta collaborazione con Claude di Anthropic, un assistente basato su modelli linguistici di grandi dimensioni.

Il risultato è un codice funzionante e testato sul campo, ma soprattutto una riflessione concreta su come l’IA generativa possa affiancare — non sostituire — il ricercatore nella produzione di strumenti digitali per la ricerca umanistica. Il controllo progettuale, le scelte interpretative e la verifica dei risultati sono rimasti sempre in capo al ricercatore umano.

---

Provalo e contribuisci

AITracer è in sviluppo attivo. Ogni test sul campo, ogni segnalazione di problemi e ogni suggerimento è prezioso per migliorarlo.

• 📦 Codice sorgente e release: github.com/lad-sapienza/ai-tracer
• 🐛 Segnala un problema: github.com/lad-sapienza/ai-tracer/issues
• 📖 Approfondisci: lad.saras.uniroma1.it/blog/ai-tracer
• ✉️ Contatti: julian.bogdani@uniroma1.it