Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Dati di input nuvola di punti 3D
Per creare un processo di etichettatura con nuvole di punti 3D, è necessario creare un file manifest di input. Utilizza questo argomento per conoscere i requisiti di formattazione del file manifest di input per ogni tipo di attività. Per informazioni sui formati di dati di input grezzi che Ground Truth accetta per i processi di etichettatura nuvola di punti 3D, consulta la sezione [Formati dati 3D non elaborati accettati](sms-point-cloud-raw-data-types.md).
Utilizza il [tipo di attività di etichettatura](https://docs.aws.amazon.com/sagemaker/latest/dg/sms-point-cloud-task-types.html) per scegliere un argomento su [File di manifesto di input per processi di etichettatura in una nuvola di punti 3D](sms-point-cloud-input-manifest.md) per conoscere i requisiti di formattazione per ogni riga del file manifest di input.
**Topics**
+ [Formati dati 3D non elaborati accettati](sms-point-cloud-raw-data-types.md)
+ [File di manifesto di input per processi di etichettatura in una nuvola di punti 3D](sms-point-cloud-input-manifest.md)
+ [Comprensione dei sistemi di coordinate e della fusione dei sensori](sms-point-cloud-sensor-fusion-details.md)
# Formati dati 3D non elaborati accettati
Ground Truth utilizza i dati della nuvola di punti 3D per eseguire il rendering di scene 3D annotate dai worker. In questa sezione vengono descritti i formati di dati non elaborati accettati per i dati delle nuvole di punti e i dati di fusione dei sensori per un frame di nuvola di punti. Per informazioni su come creare un file manifest di input per connettere i file di dati di input non elaborati con Ground Truth, consulta [File di manifesto di input per processi di etichettatura in una nuvola di punti 3D](sms-point-cloud-input-manifest.md).
Per ogni fotogramma, Ground Truth supporta i file Compact Binary Pack Format (.bin) e ASCII (.txt). Questi file contengono informazioni sulla posizione (coordinate `x`, `y` e `z`) di tutti i punti che compongono il frame e, facoltativamente, informazioni sul colore dei pixel di ciascun punto per le nuvole di punti colorate. Quando si crea un file manifest di input del processo di etichettatura con nuvole di punti 3D, è possibile specificare il formato dei dati non elaborati nel parametro `format`.
Nella tabella seguente sono elencati gli elementi che Ground Truth supporta nei file fotogramma di nuvola di punti per descrivere i singoli punti.
****
| Symbol | Valore |
| --- | --- |
| `x` | Coordinata x del punto. |
| `y` | Coordinata y del punto. |
| `z` | Coordinata z del punto. |
| `i` | L'intensità del punto. |
| `r` | Il componente canale di colore rosso. Un valore a 8 bit (0-255). |
| `g` | Il componente canale di colore verde. Un valore a 8 bit (0-255) |
| `b` | Il componente del canale di colore blu. Un valore a 8 bit (0-255) |
Ground Truth presuppone quanto segue sui dati di input:
+ Tutte le coordinate posizionali (x, y, z) sono espresse in metri.
+ Tutte le intestazioni di posa (qx, qy, qz, qw) sono misurate in [quaternioni](https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation) spaziali.
## Formato pacchetto binario compatto
Il formato pacchetto binario compatto rappresenta una nuvola di punti come un insieme ordinato di un flusso di punti. Ogni punto del flusso è un pacchetto binario ordinato di valori in virgola mobile a 4 byte in alcune varianti del formato `xyzirgb`. Gli elementi `x`, `y` e `z` sono necessari e ulteriori informazioni su quel pixel possono essere incluse in diversi modi utilizzando `i`, `r`, `g` e `b`.
Per utilizzare un file binario per inserire i dati del fotogramma nuvola di punti in un processo di etichettatura con nuvole di punti 3D Ground Truth, immetti `binary/` nel parametro `format` per il file manifest di input e sostituisci `` con l'ordine degli elementi in ogni pacchetto binario. Ad esempio, è possibile immettere una delle seguenti opzioni per il parametro `format`.
+ `binary/xyzi`: quando si utilizza questo formato, il flusso dell'elemento punto sarebbe nel seguente ordine: `x1y1z1i1x2y2z2i2...`
+ `binary/xyzrgb`: quando si utilizza questo formato, il flusso dell'elemento punto sarebbe nel seguente ordine: `x1y1z1r1g1b1x2y2z2r2g2b2...`
+ `binary/xyzirgb`: quando si utilizza questo formato, il flusso dell'elemento punto sarebbe nel seguente ordine: `x1y1z1i1r1g1b1x2y2z2i2r2g2b2...`
Quando si utilizza un file binario per i dati frame nuvola di punti, se non si immette un valore per `format`, viene utilizzato il formato predefinito `binary/xyzi` del pacchetto.
## Formato ASCII
Il formato ASCII utilizza un file di testo per rappresentare una nuvola di punti, in cui ogni riga del file nuvola di punti ASCII rappresenta un singolo punto. Ogni punto è una linea del file di testo e contiene valori separati da spazi bianchi, ognuno dei quali è un valore ASCII in virgola mobile a 4 byte. Gli elementi `x`, `y` e `z` sono necessari per ogni punto e ulteriori informazioni su quel punto possono essere incluse in diversi modi utilizzando `i`, `r`, `g` e `b`.
Per utilizzare un file di testo per inserire i dati del fotogramma di nuvola di punti in un processo di etichettatura di nuvole di punti Ground Truth 3D, immetti `text/` nel parametro `format` per il file manifesto di input e sostituisci `` con l'ordine degli elementi punto su ogni riga.
Ad esempio, se immetti `text/xyzi` per `format`, il file di testo per ogni frame nuvola di punti dovrebbe essere simile al seguente:
```
x1 y1 z1 i1
x2 y2 z2 i2
...
...
```
Se immetti `text/xyzrgb`, il file di testo dovrebbe essere simile al seguente:
```
x1 y1 z1 r1 g1 b1
x2 y2 z2 r2 g2 b1
...
...
```
Quando utilizzi un file di testo per i dati frame della nuvola di punti, se non immetti un valore per `format`, verrà utilizzato il formato predefinito `text/xyzi`.
## Limiti di risoluzione delle nuvole di punti
Ground Truth non ha un limite di risoluzione per i fotogrammi di nuvole di punti 3D. Tuttavia, si consiglia di limitare ogni frame di nuvola di punti a 500K punti per ottenere prestazioni ottimali. Quando Ground Truth esegue il rendering della visualizzazione della nuvola di punti 3D, questo deve essere visualizzabile sui computer dei worker, il che dipende dall'hardware del computer dei worker. I frame di nuvola di punti superiori a 1 milione di punti potrebbero non essere visualizzati su macchine standard o richiedere troppo tempo per il caricamento.
# File di manifesto di input per processi di etichettatura in una nuvola di punti 3D
Quando si crea un processo di etichettatura, si fornisce un file manifest di input in cui ogni riga del manifest descrive un'unità di attività che deve essere completata dagli annotatori. Il formato del file manifest di input dipende dal tipo di attività.
+ Se crei un processo di **rilevamento di oggetti** o di **segmentazione semantica** della nuvola di punti 3D, ogni riga del file manifest di input contiene informazioni su un singolo frame nuvola di punti 3D. Questo è chiamato *manifest di input del frame di nuvola di punti*. Per ulteriori informazioni, consulta [Creazione di un file manifest di input del frame di nuvola di punti](sms-point-cloud-single-frame-input-data.md).
+ Se crei un processo di etichettatura di **tracciamento di oggetti** di nuvola di punti 3D, ogni riga del file manifest di input contiene una sequenza di frame di nuvola di punti 3D e dati associati. Questo è chiamato un *manifest di input della sequenza di nuvola di punti*. Per ulteriori informazioni, consulta [Creazione di un file manifest di input della sequenza di nuvole di punti](sms-point-cloud-multi-frame-input-data.md).
# Creazione di un file manifest di input del frame di nuvola di punti
Il manifest è un file con codifica UTF-8 in cui ogni riga è un oggetto JSON completo e valido. Ogni riga è delimitata da un’interruzione di riga standard, \$1n oppure \$1r\$1n. Dal momento che ogni riga deve essere un oggetto JSON valido, i caratteri di interruzione di riga senza escape non sono consentiti. Nel file manifest di input a frame singolo, ogni riga del manifest contiene i dati per un singolo frame di nuvola di punti. I dati del frame di nuvola di punti possono essere memorizzati in formato binario o ASCII (vedi [Formati dati 3D non elaborati accettati](sms-point-cloud-raw-data-types.md)). Questa è la formattazione del file manifest necessaria per il rilevamento di oggetti nubi di punti 3D e la segmentazione semantica. Facoltativamente, è anche possibile fornire dati di fusione del sensore della telecamera per ogni frame della nuvola di punti.
Ground Truth supporta la fusione del sensore della nuvola di punti e della videocamera nel [sistema di coordinate mondiale](sms-point-cloud-sensor-fusion-details.md#sms-point-cloud-world-coordinate-system) per tutte le modalità. Se è possibile ottenere il sensore 3D estrinseco (come un estrinseco LiDAR), si consiglia di trasformare i frame di nuvole di punti 3D nel sistema di coordinate mondiali utilizzando l'estrinseco. Per ulteriori informazioni, consulta [Fusione dei sensori](sms-point-cloud-sensor-fusion-details.md#sms-point-cloud-sensor-fusion).
Tuttavia, se non è possibile ottenere una nuvola di punti nel sistema di coordinate mondiali, è possibile fornire le coordinate nel sistema di coordinate originale in cui sono stati acquisiti i dati. Se si forniscono i dati della telecamera per la fusione dei sensori, si consiglia di fornire il sensore LiDAR e la posizione della telecamera nel sistema di coordinate mondiali.
Per creare un file manifest di input a frame singolo, si identificherà la posizione di ogni frame nuvola di punti che si desidera che i worker etichettino utilizzando la chiave `source-ref`. Inoltre, è necessario utilizzare la chiave `source-ref-metadata` per identificare il formato del set di dati, un timestamp per tale frame e, facoltativamente, i dati di fusione del sensore e le immagini della videocamera.
Nell'esempio seguente viene illustrata la sintassi utilizzata per un file manifest di input per un processo di etichettatura con nuvola di punti a frame singolo. L'esempio include due frame di nuvola di punti. Per informazioni dettagliate su ciascun parametro, consulta la tabella che segue questo esempio.
**Importante**
Ogni riga del file manifest di input deve essere in formato [JSON Lines](http://jsonlines.org/). Il seguente blocco di codice mostra un file di input di un file manifest con due oggetti JSON. Ogni oggetto JSON viene utilizzato per indicare e fornire dettagli su un fotogramma di nuvola di punti singolo. Gli oggetti JSON sono stati espansi per motivi di leggibilità, ma è necessario ridurre al minimo ogni oggetto JSON per adattarlo a una singola riga durante la creazione di un file manifest di input. Un esempio viene fornito in questo blocco di codice.
```
{
"source-ref": "s3://amzn-s3-demo-bucket/examplefolder/frame1.bin",
"source-ref-metadata":{
"format": "binary/xyzi",
"unix-timestamp": 1566861644.759115,
"ego-vehicle-pose":{
"position": {
"x": -2.7161461413869947,
"y": 116.25822288149078,
"z": 1.8348751887989483
},
"heading": {
"qx": -0.02111296123795955,
"qy": -0.006495469416730261,
"qz": -0.008024565904865688,
"qw": 0.9997181192298087
}
},
"prefix": "s3://amzn-s3-demo-bucket/lidar_singleframe_dataset/someprefix/",
"images": [
{
"image-path": "images/frame300.bin_camera0.jpg",
"unix-timestamp": 1566861644.759115,
"fx": 847.7962624528487,
"fy": 850.0340893791985,
"cx": 576.2129134707038,
"cy": 317.2423573573745,
"k1": 0,
"k2": 0,
"k3": 0,
"k4": 0,
"p1": 0,
"p2": 0,
"skew": 0,
"position": {
"x": -2.2722515189268138,
"y": 116.86003310568965,
"z": 1.454614668542299
},
"heading": {
"qx": 0.7594754093069037,
"qy": 0.02181790885672969,
"qz": -0.02461725233103356,
"qw": -0.6496916273040025
},
"camera-model": "pinhole"
}]
}
}
{
"source-ref": "s3://amzn-s3-demo-bucket/examplefolder/frame2.bin",
"source-ref-metadata":{
"format": "binary/xyzi",
"unix-timestamp": 1566861632.759133,
"ego-vehicle-pose":{
"position": {
"x": -2.7161461413869947,
"y": 116.25822288149078,
"z": 1.8348751887989483
},
"heading": {
"qx": -0.02111296123795955,
"qy": -0.006495469416730261,
"qz": -0.008024565904865688,
"qw": 0.9997181192298087
}
},
"prefix": "s3://amzn-s3-demo-bucket/lidar_singleframe_dataset/someprefix/",
"images": [
{
"image-path": "images/frame300.bin_camera0.jpg",
"unix-timestamp": 1566861644.759115,
"fx": 847.7962624528487,
"fy": 850.0340893791985,
"cx": 576.2129134707038,
"cy": 317.2423573573745,
"k1": 0,
"k2": 0,
"k3": 0,
"k4": 0,
"p1": 0,
"p2": 0,
"skew": 0,
"position": {
"x": -2.2722515189268138,
"y": 116.86003310568965,
"z": 1.454614668542299
},
"heading": {
"qx": 0.7594754093069037,
"qy": 0.02181790885672969,
"qz": -0.02461725233103356,
"qw": -0.6496916273040025
},
"camera-model": "pinhole"
}]
}
}
```
Quando crei un file manifest di input, è necessario ridurre gli oggetti JSON per adattarli a una singola riga. Ad esempio, in un file manifest di input, il blocco di codice precedente apparirebbe come segue:
```
{"source-ref":"s3://amzn-s3-demo-bucket/examplefolder/frame1.bin","source-ref-metadata":{"format":"binary/xyzi","unix-timestamp":1566861644.759115,"ego-vehicle-pose":{"position":{"x":-2.7161461413869947,"y":116.25822288149078,"z":1.8348751887989483},"heading":{"qx":-0.02111296123795955,"qy":-0.006495469416730261,"qz":-0.008024565904865688,"qw":0.9997181192298087}},"prefix":"s3://amzn-s3-demo-bucket/lidar_singleframe_dataset/someprefix/","images":[{"image-path":"images/frame300.bin_camera0.jpg","unix-timestamp":1566861644.759115,"fx":847.7962624528487,"fy":850.0340893791985,"cx":576.2129134707038,"cy":317.2423573573745,"k1":0,"k2":0,"k3":0,"k4":0,"p1":0,"p2":0,"skew":0,"position":{"x":-2.2722515189268138,"y":116.86003310568965,"z":1.454614668542299},"heading":{"qx":0.7594754093069037,"qy":0.02181790885672969,"qz":-0.02461725233103356,"qw":-0.6496916273040025},"camera-model":"pinhole"}]}}
{"source-ref":"s3://amzn-s3-demo-bucket/examplefolder/frame2.bin","source-ref-metadata":{"format":"binary/xyzi","unix-timestamp":1566861632.759133,"ego-vehicle-pose":{"position":{"x":-2.7161461413869947,"y":116.25822288149078,"z":1.8348751887989483},"heading":{"qx":-0.02111296123795955,"qy":-0.006495469416730261,"qz":-0.008024565904865688,"qw":0.9997181192298087}},"prefix":"s3://amzn-s3-demo-bucket/lidar_singleframe_dataset/someprefix/","images":[{"image-path":"images/frame300.bin_camera0.jpg","unix-timestamp":1566861644.759115,"fx":847.7962624528487,"fy":850.0340893791985,"cx":576.2129134707038,"cy":317.2423573573745,"k1":0,"k2":0,"k3":0,"k4":0,"p1":0,"p2":0,"skew":0,"position":{"x":-2.2722515189268138,"y":116.86003310568965,"z":1.454614668542299},"heading":{"qx":0.7594754093069037,"qy":0.02181790885672969,"qz":-0.02461725233103356,"qw":-0.6496916273040025},"camera-model":"pinhole"}]}}
```
La tabella seguente mostra i parametri che è possibile includere nel file manifest di input:
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `source-ref` | Sì | Stringa **Formato valore stringa accettato**: `s3:////point-cloud-frame-file` | Posizione Amazon S3 di un singolo fotogramma di nuvola di punti. |
| `source-ref-metadata` | Sì | Oggetto JSON **Parametri accettati**: `format`, `unix-timestamp`, `ego-vehicle-pose`, `position`, `prefix`, `images` | Utilizzare questo parametro per includere ulteriori informazioni sulla nuvola di punti in `source-ref` e per fornire i dati della telecamera per la fusione dei sensori. |
| `format` | No | Stringa **Valori stringa accettati**: `"binary/xyz"`, `"binary/xyzi"`, `"binary/xyzrgb"`, `"binary/xyzirgb"`, `"text/xyz"`, `"text/xyzi"`, `"text/xyzrgb"`, `"text/xyzirgb"` **Valori predefiniti:** Quando il file identificato in `source-ref` ha un'estensione.bin, `binary/xyzi` Quando il file identificato in `source-ref` ha un'estensione.txt, `text/xyzi` | Utilizza questo parametro per specificare il formato dei dati della nuvola di punti. Per ulteriori informazioni, consulta [Formati dati 3D non elaborati accettati](sms-point-cloud-raw-data-types.md). |
| `unix-timestamp` | Sì | Numero Un timestamp unix. | Il timestamp unix è il numero di secondi dal 1° gennaio 1970 fino all'ora UTC in cui i dati sono stati raccolti da un sensore. |
| `ego-vehicle-pose` | No | Oggetto JSON | La posa del dispositivo utilizzato per raccogliere i dati della nuvola di punti. Per ulteriori informazioni su questo parametro, consulta [Includi le informazioni sulla posa del veicolo nel file manifest di input](#sms-point-cloud-single-frame-ego-vehicle-input). |
| `prefix` | No | Stringa **Formato valore stringa accettato**: `s3:////` | La posizione in Amazon S3 in cui vengono memorizzati i metadati, ad esempio le immagini della telecamera, per questo fotogramma. Il prefisso deve terminare con una barra: `/`. |
| `images` | No | List | Un elenco di parametri che descrivono le immagini della telecamera a colori utilizzate per la fusione dei sensori. È possibile includere fino a 8 immagini in questo elenco. Per ulteriori informazioni sui parametri richiesti per ogni immagine, consulta [Inserimento dei dati della videocamera nel manifest di input](#sms-point-cloud-single-frame-image-input). |
## Includi le informazioni sulla posa del veicolo nel file manifest di input
Utilizza la posizione del veicolo ego per fornire informazioni sulla posizione del veicolo utilizzato per acquisire i dati delle nuvole di punti. Ground Truth utilizza queste informazioni per calcolare la matrice estrinseca LiDAR.
Ground Truth utilizza matrici estrinseche per proiettare etichette da e verso la scena 3D e le immagini 2D. Per ulteriori informazioni, consulta [Fusione dei sensori](sms-point-cloud-sensor-fusion-details.md#sms-point-cloud-sensor-fusion).
Nella tabella seguente vengono fornite ulteriori informazioni sui parametri `position` e orientamento (`heading`) necessari quando si forniscono informazioni sul veicolo ego.
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `position` | Sì | Oggetto JSON **Parametri obbligatori**: `x`, `y` e `z`. Immetti i numeri per questi parametri. | Il vettore di traslazione del veicolo ego nel sistema di coordinate mondiale. |
| `heading` | Sì | Oggetto JSON **Parametri obbligatori**: `qx`, `qy`, `qz` e `qw`. Immetti i numeri per questi parametri. | L'orientamento del frame di riferimento del dispositivo o del sensore montato sul veicolo che rileva l'ambiente circostante, misurato in [quaternioni](https://en.wikipedia.org/wiki/Quaternion), (`qx`, `qy`, `qz`, `qw`) in un sistema di coordinate. |
## Inserimento dei dati della videocamera nel manifest di input
Per includere i dati della videocamera in un frame, utilizza i seguenti parametri per fornire informazioni su ciascuna immagine. La colonna **Obbligatorio** riportata di seguito si applica quando il parametro `images` è incluso nel file manifest di input in `source-ref-metadata`. Non è necessario includere immagini nel file manifest di input.
Se includi immagini della videocamera, è necessario includere informazioni sui parametri `position` e `heading` utilizzare la cattura delle immagini nel sistema di coordinate mondiali.
Se le immagini sono distorte, Ground Truth può automaticamente annullarle utilizzando le informazioni fornite sull'immagine nel file manifest di input, inclusi i coefficienti di distorsione (`k1`, `k2`, `k3`, `k4`, `p1`, `p1`), il modello della telecamera e la matrice intrinseca della telecamera. La matrice intrinseca è costituita dalla lunghezza focale (`fx`, `fy`) e dal punto principale (`cx`, `cy)`. Consulta [Matrice intrinseca](sms-point-cloud-sensor-fusion-details.md#sms-point-cloud-intrinsic) per scoprire come Ground Truth utilizza le funzioni intrinseche della telecamera. Se i coefficienti di distorsione non sono inclusi, Ground Truth non altera un'immagine.
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `image-path` | Sì | Stringa **Esempio di formato**: `/` | La posizione relativa all'interno di Amazon S3 del file di immagine. Questo percorso relativo verrà aggiunto al percorso specificato in `prefix`. |
| `unix-timestamp` | Sì | Numero | Il timestamp unix è il numero di secondi dal 1° gennaio 1970 fino all'ora UTC in cui i dati sono stati raccolti da una fotocamera. |
| `camera-model` | No | Stringa: **Valori accettati**: `"pinhole"`, `"fisheye"` **Default**: `"pinhole"` | Il modello della telecamera utilizzata per catturare l'immagine. Queste informazioni vengono utilizzate per non distorcere le immagini della telecamera. |
| `fx, fy` | Sì | Numeri | La lunghezza focale della telecamera, nelle direzioni x (`fx`) e y (`fy`). |
| `cx, cy` | Sì | Numeri | Le coordinate x (`cx`) e y (`cy`) del punto principale. |
| `k1, k2, k3, k4` | No | Numero | Coefficienti di distorsione radiale. Supportato sia per i modelli di fotocamere **fisheye** e a **foro stenopeico**. |
| `p1, p2` | No | Numero | Coefficienti di distorsione tangenziale. Supportato per i modelli di fotocamera a **foro stenopeico**. |
| `skew` | No | Numero | Parametro per misurare l'inclinazione di un'immagine. |
| `position` | Sì | Oggetto JSON **Parametri obbligatori**: `x`, `y` e `z`. Immetti i numeri per questi parametri. | La posizione o l'origine del frame di riferimento della telecamera montata sul veicolo che cattura le immagini. |
| `heading` | Sì | Oggetto JSON **Parametri obbligatori**: `qx`, `qy`, `qz` e `qw`. Immetti i numeri per questi parametri. | L'orientamento del fotogramma di riferimento della telecamera montata sul veicolo che cattura le immagini, misurato utilizzando [quaternioni](https://en.wikipedia.org/wiki/Quaternion), (`qx`, `qy`, `qz`, `qw`), nel sistema di coordinate mondiali. |
## Limiti dei fotogrammi della nuvola di punti
È possibile includere fino a 100.000 fotogrammi della nuvola di punti nel file manifest di input. Il processo di etichettatura con nuvola di punti 3D ha tempi di pre-elaborazione più lunghi rispetto ad altri tipi di attività di Ground Truth. Per ulteriori informazioni, consulta [Tempo di pre-elaborazione di un processo](sms-point-cloud-general-information.md#sms-point-cloud-job-creation-time).
# Creazione di un file manifest di input della sequenza di nuvole di punti
Il manifest è un file con codifica UTF-8 in cui ogni riga è un oggetto JSON completo e valido. Ogni riga è delimitata da un’interruzione di riga standard, \$1n oppure \$1r\$1n. Dal momento che ogni riga deve essere un oggetto JSON valido, i caratteri di interruzione di riga senza escape non sono consentiti. Nel file manifest di input della sequenza di nuvola di punti, ogni riga del manifest contiene una sequenza di frame di nuvola di punti. I dati della nuvola di punti per ogni frame della sequenza possono essere memorizzati in formato binario o ASCII. Per ulteriori informazioni, consulta [Formati dati 3D non elaborati accettati](sms-point-cloud-raw-data-types.md). Questa è la formattazione del file manifest necessaria per il tracciamento di oggetti nuvola di punti 3D. Facoltativamente, è anche possibile fornire dati relativi all'attributo dei punti e alla fusione dei sensori della telecamera per ogni frame della nuvola di punti. Quando crei un file manifest di input di sequenza, devi fornire i dati di fusione dei sensori e della videocamera e LiDAR in un [sistema di coordinate mondiali](sms-point-cloud-sensor-fusion-details.md#sms-point-cloud-world-coordinate-system).
Nell'esempio seguente viene illustrata la sintassi utilizzata per un file manifest di input quando ogni riga del manifest è un file di sequenza. Ogni riga del file manifest di input deve essere in formato [JSON Lines](http://jsonlines.org/).
```
{"source-ref": "s3://amzn-s3-demo-bucket/example-folder/seq1.json"}
{"source-ref": "s3://amzn-s3-demo-bucket/example-folder/seq2.json"}
```
I dati per ogni sequenza di frame di nuvola di punti devono essere memorizzati in un oggetto dati JSON. Di seguito è riportato un esempio del formato utilizzato per un file di sequenza. Le informazioni su ogni frame sono incluse come oggetto JSON e sono elencate in `frames`. Questo è un esempio di file di sequenza con file di frame a due nuvole di punti, `frame300.bin` e `frame303.bin`. *...*Viene utilizzato per indicare dove è necessario includere informazioni per frame aggiuntivi. Aggiungi un oggetto JSON per ogni fotogramma della sequenza.
Il seguente blocco di codice include un oggetto JSON per un singolo file di sequenza. L'oggetto JSON è stato espanso per garantire la leggibilità.
```
{
"seq-no": 1,
"prefix": "s3://amzn-s3-demo-bucket/example_lidar_sequence_dataset/seq1/",
"number-of-frames": 100,
"frames":[
{
"frame-no": 300,
"unix-timestamp": 1566861644.759115,
"frame": "example_lidar_frames/frame300.bin",
"format": "binary/xyzi",
"ego-vehicle-pose":{
"position": {
"x": -2.7161461413869947,
"y": 116.25822288149078,
"z": 1.8348751887989483
},
"heading": {
"qx": -0.02111296123795955,
"qy": -0.006495469416730261,
"qz": -0.008024565904865688,
"qw": 0.9997181192298087
}
},
"images": [
{
"image-path": "example_images/frame300.bin_camera0.jpg",
"unix-timestamp": 1566861644.759115,
"fx": 847.7962624528487,
"fy": 850.0340893791985,
"cx": 576.2129134707038,
"cy": 317.2423573573745,
"k1": 0,
"k2": 0,
"k3": 0,
"k4": 0,
"p1": 0,
"p2": 0,
"skew": 0,
"position": {
"x": -2.2722515189268138,
"y": 116.86003310568965,
"z": 1.454614668542299
},
"heading": {
"qx": 0.7594754093069037,
"qy": 0.02181790885672969,
"qz": -0.02461725233103356,
"qw": -0.6496916273040025
},
"camera-model": "pinhole"
}]
},
{
"frame-no": 303,
"unix-timestamp": 1566861644.759115,
"frame": "example_lidar_frames/frame303.bin",
"format": "text/xyzi",
"ego-vehicle-pose":{...},
"images":[{...}]
},
...
]
}
```
La tabella seguente fornisce dettagli sui parametri di primo livello di un file di sequenza. Per informazioni dettagliate sui parametri richiesti per i singoli frame nel file di sequenza, consulta [Parametri per singoli frame di nuvole di punti](#sms-point-cloud-multi-frame-input-single-frame).
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `seq-no` | Sì | Numero intero | Il numero ordinato della sequenza. |
| `prefix` | Sì | Stringa **Valori accettati**: `s3:////` | Posizione Amazon S3 in cui si trovano i file di sequenza. Il prefisso deve terminare con una barra: `/`. |
| `number-of-frames` | Sì | Numero intero | Numero totale di frame inclusi nel file di sequenza. Questo numero deve corrispondere al numero totale di frame elencati nel parametro `frames` nella riga successiva. |
| `frames` | Sì | Elenco degli oggetti JSON | Un elenco di dati frame. La lunghezza dell'elenco deve essere uguale `number-of-frames`. Nell'interfaccia utente di lavoro, i frame in una sequenza saranno uguali all'ordine dei frame in questo array. Per ulteriori informazioni sul formato di ogni frame, consulta [Parametri per singoli frame di nuvole di punti](#sms-point-cloud-multi-frame-input-single-frame). |
## Parametri per singoli frame di nuvole di punti
La tabella seguente mostra i parametri che è possibile includere nel file manifest di input.
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `frame-no` | No | Numero intero | Il numero di frame. Si tratta di un identificatore opzionale specificato dal cliente per identificare il frame all'interno di una sequenza. Non è utilizzato da Ground Truth. |
| `unix-timestamp` | Sì | Numero | Il timestamp unix è il numero di secondi dal 1° gennaio 1970 fino all'ora UTC in cui i dati sono stati raccolti da un sensore. Il timestamp per ogni frame deve essere diverso e i timestamp devono essere sequenziali perché vengono utilizzati per l'interpolazione cuboide. Idealmente, questo dovrebbe essere il timestamp reale al momento della raccolta dei dati. Se questo non è disponibile, è necessario utilizzare una sequenza incrementale di timestamp, in cui il primo frame del file di sequenza corrisponde al primo timestamp della sequenza. |
| `frame` | Sì | Stringa **Esempio di formato** `/` | La posizione relativa, in Amazon S3, del file di sequenza. Questo percorso relativo verrà aggiunto al percorso specificato in `prefix`. |
| `format` | No | Stringa **Valori stringa accettati**: `"binary/xyz"`, `"binary/xyzi"`, `"binary/xyzrgb"`, `"binary/xyzirgb"`, `"text/xyz"`, `"text/xyzi"`, `"text/xyzrgb"`, `"text/xyzirgb"` **Valori predefiniti:** Quando il file identificato in `source-ref` ha un'estensione.bin, `binary/xyzi` Quando il file identificato in `source-ref` ha un'estensione.txt, `text/xyzi` | Utilizza questo parametro per specificare il formato dei dati della nuvola di punti. Per ulteriori informazioni, consulta [Formati dati 3D non elaborati accettati](sms-point-cloud-raw-data-types.md). |
| `ego-vehicle-pose` | No | Oggetto JSON | La posa del dispositivo utilizzato per raccogliere i dati della nuvola di punti. Per ulteriori informazioni su questo parametro, consulta [Includi le informazioni sulla posa del veicolo nel file manifest di input](#sms-point-cloud-multi-frame-ego-vehicle-input). |
| `prefix` | No | Stringa **Formato valore stringa accettato**: `s3:////` | La posizione in Amazon S3 in cui vengono memorizzati i metadati, ad esempio le immagini della telecamera, per questo fotogramma. Il prefisso deve terminare con una barra: `/`. |
| `images` | No | List | Elenco dei parametri che descrivono le immagini della telecamera a colori utilizzate per la fusione dei sensori. È possibile includere fino a 8 immagini in questo elenco. Per ulteriori informazioni sui parametri richiesti per ogni immagine, consulta [Inserimento dei dati della telecamera nel manifest di input](#sms-point-cloud-multi-frame-image-input). |
## Includi le informazioni sulla posa del veicolo nel file manifest di input
Utilizza la posizione del veicolo ego per fornire informazioni sulla posizione del veicolo utilizzato per acquisire i dati delle nuvole di punti. Ground Truth utilizza queste informazioni per calcolare le matrici estrinseche LiDAR.
Ground Truth utilizza matrici estrinseche per proiettare etichette da e verso la scena 3D e le immagini 2D. Per ulteriori informazioni, consulta [Fusione dei sensori](sms-point-cloud-sensor-fusion-details.md#sms-point-cloud-sensor-fusion).
Nella tabella seguente vengono fornite ulteriori informazioni sui parametri `position` e orientamento (`heading`) necessari quando si forniscono informazioni sul veicolo ego.
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `position` | Sì | Oggetto JSON **Parametri obbligatori**: `x`, `y` e `z`. Immetti i numeri per questi parametri. | Il vettore di traslazione del veicolo ego nel sistema di coordinate mondiale. |
| `heading` | Sì | Oggetto JSON **Parametri obbligatori**: `qx`, `qy`, `qz` e `qw`. Immetti i numeri per questi parametri. | L'orientamento del frame di riferimento del dispositivo o del sensore montato sul veicolo che rileva l'ambiente circostante, misurato in [quaternioni](https://en.wikipedia.org/wiki/Quaternion), (`qx`, `qy`, `qz`, `qw`) in un sistema di coordinate. |
## Inserimento dei dati della telecamera nel manifest di input
Per includere i dati della telecamera a colori in un frame, utilizza i seguenti parametri per fornire informazioni su ciascuna immagine. La colonna **Obbligatorio** della tabella seguente si applica quando il parametro `images` è incluso nel file manifest di input. Non è necessario includere immagini nel file manifest di input.
Se si includono immagini della telecamera, è necessario includere informazioni sulla posizione `position` e sull’orientamento (`heading`) della telecamera utilizzata per catturare le immagini.
Se le immagini sono distorte, Ground Truth può automaticamente annullarle utilizzando le informazioni fornite sull'immagine nel file manifest di input, inclusi i coefficienti di distorsione (`k1`, `k2`, `k3`, `k4`, `p1`, `p1`), il modello della telecamera e la lunghezza focale (`fx`, `fy`) e il punto principale (`cx`, `cy)`. Per ulteriori informazioni su questi coefficienti e immagini non distorte, consulta [Camera calibration with OpenCV](https://docs.opencv.org/2.4.13.7/doc/tutorials/calib3d/camera_calibration/camera_calibration.html). Se i coefficienti di distorsione non sono inclusi, Ground Truth non altera un'immagine.
****
| Parametro | Obbligatorio | Valori accettati | Description |
| --- | --- | --- | --- |
| `image-path` | Sì | Stringa **Esempio di formato**: `/` | La posizione relativa all'interno di Amazon S3 del file di immagine. Questo percorso relativo verrà aggiunto al percorso specificato in `prefix`. |
| `unix-timestamp` | Sì | Numero | Il timestamp dell'immagine. |
| `camera-model` | No | Stringa: **Valori accettati**: `"pinhole"`, `"fisheye"` **Default**: `"pinhole"` | Il modello della telecamera utilizzata per catturare l'immagine. Queste informazioni vengono utilizzate per non distorcere le immagini della telecamera. |
| `fx, fy` | Sì | Numeri | La lunghezza focale della telecamera, nelle direzioni x (`fx`) e y (`fy`). |
| `cx, cy` | Sì | Numeri | Le coordinate x (`cx`) e y (`cy`) del punto principale. |
| `k1, k2, k3, k4` | No | Numero | Coefficienti di distorsione radiale. Supportato sia per i modelli di fotocamere **fisheye** e a **foro stenopeico**. |
| `p1, p2` | No | Numero | Coefficienti di distorsione tangenziale. Supportato per i modelli di fotocamera a **foro stenopeico**. |
| `skew` | No | Numero | Parametro per misurare qualsiasi inclinazione nota nell'immagine. |
| `position` | Sì | Oggetto JSON **Parametri obbligatori**: `x`, `y` e `z`. Immetti i numeri per questi parametri. | La posizione o l'origine del frame di riferimento della telecamera montata sul veicolo che cattura le immagini. |
| `heading` | Sì | Oggetto JSON **Parametri obbligatori**: `qx`, `qy`, `qz` e `qw`. Immetti i numeri per questi parametri. | L'orientamento del frame di riferimento della telecamera montata sul veicolo che cattura le immagini, misurato utilizzando [quaternioni](https://en.wikipedia.org/wiki/Quaternion), `qx`, (`qy`, `qz`, `qw`). |
## Limiti dei frame del file di sequenza e della nuvola di punti
È possibile includere fino a 100.000 sequenze di frame di nuvola di punti nel file manifest di input. È possibile includere fino a 500 frame di nuvola di punti in ogni file di sequenza.
Tieni presente che il processo di etichettatura con nuvola di punti 3D ha tempi di pre-elaborazione più lunghi rispetto ad altri tipi di attività Ground Truth. Per ulteriori informazioni, consulta [Tempo di pre-elaborazione di un processo](sms-point-cloud-general-information.md#sms-point-cloud-job-creation-time).
# Comprensione dei sistemi di coordinate e della fusione dei sensori
I dati della nuvola di punti si trovano sempre in un sistema di coordinate. Questo sistema di coordinate può essere locale per il veicolo o il dispositivo che rileva l'ambiente circostante oppure può essere un sistema di coordinate mondiali. Quando si utilizzano processi di etichettatura con nuvole di punti Ground Truth 3D, tutte le annotazioni vengono generate utilizzando il sistema di coordinate dei dati di input. Per alcuni tipi di attività e funzionalità di etichettatura dei processi, è necessario fornire i dati in un sistema di coordinate mondiali
In questo argomento verranno illustrate le seguenti informazioni:
+ Quando è *necessario fornire* dati di input in un sistema di coordinate mondiali o in un sistema di riferimento globale.
+ Che cos'è una coordinata mondiale e come convertire i dati della nuvola di punti in un sistema di coordinate mondiale.
+ Come è possibile utilizzare le matrici estrinseche del sensore e della telecamera per fornire dati di posa quando si utilizza la fusione dei sensori.
## Coordinamento dei requisiti di sistema per i processi di etichettatura
Se i dati della nuvola di punti sono stati raccolti in un sistema di coordinate locale, è possibile utilizzare una matrice estrinseca del sensore utilizzato per raccogliere i dati per convertirli in un sistema di coordinate mondiali o in un quadro di riferimento globale. Se non è possibile ottenere una matrice estrinseca per i dati della nuvola di punti e, di conseguenza, non è possibile ottenere nuvole di punti in un sistema di coordinate mondiale, è possibile fornire dati di nuvole di punti in un sistema di coordinate locale per i tipi di attività di rilevamento di oggetti nuvola di punti 3D e segmentazione semantica.
Per il tracciamento degli oggetti, è necessario fornire i dati della nuvola di punti in un sistema di coordinate mondiale. Questo perché quando si tracciano oggetti su più frame, il veicolo ego stesso si muove nel mondo e quindi tutti i frame hanno bisogno di un punto di riferimento.
Se si includono i dati della telecamera per la fusione dei sensori, si consiglia di fornire le posizioni della telecamera nello stesso sistema di coordinate mondiali del sensore 3D (ad esempio un sensore LiDAR).
## Utilizzo dei dati delle nuvole di punti in un sistema di coordinate mondiali
Questa sezione spiega cos'è un sistema di coordinate mondiali (WCS), noto anche come *quadro di riferimento globale*, e spiega come è possibile fornire dati delle nuvole di punti in un sistema di coordinate mondiali.
### Che cos'è un sistema di coordinate mondiali?
Un WCS o un quadro globale di riferimento è un sistema di coordinate universale fisso in cui sono posizionati i sistemi di coordinate del veicolo e del sensore. Ad esempio, se più frame di nuvole di punti si trovano in sistemi di coordinate diversi perché sono stati raccolti da due sensori, è possibile utilizzare un WCS per tradurre tutte le coordinate di questi frame di nuvole di punti in un unico sistema di coordinate, in cui tutti i frame hanno la stessa origine, (0,0). Questa trasformazione viene eseguita traslando l'origine di ciascun frame all'origine del WCS utilizzando un vettore di traslazione e ruotando i tre assi (tipicamente x, y e z) nell'orientamento corretto utilizzando una matrice di rotazione. Questa trasformazione del corpo rigido è chiamata *trasformazione omogenea*.
Un sistema di coordinate mondiali è importante per la pianificazione globale dei percorsi, la localizzazione, la mappatura e la gestione delle simulazioni degli scenari. Ground Truth utilizza il sistema di coordinate mondiali cartesiane destrorso come quello definito nello standard [ISO 8855](https://www.iso.org/standard/51180.html), in cui l'asse x è rivolto in avanti verso il movimento dell'auto, l'asse y è a sinistra e l'asse z punta verso l'alto da terra.
Il quadro globale di riferimento dipende dai dati. Alcuni set di dati utilizzano la posizione LiDAR nel primo frame come origine. In questo scenario, tutti i frame utilizzano il primo frame come riferimento e l'intestazione e la posizione del dispositivo saranno vicini all'origine nel primo frame. Ad esempio, i dataset KITTI hanno il primo frame come riferimento per le coordinate mondiali. Altri set di dati forniscono una posizione del dispositivo che è diversa dall'origine.
Notate che questo non è il sistema di GPS/IMU coordinate, che in genere viene ruotato di 90 gradi lungo l'asse z. Se i dati della nuvola di punti si trovano in un sistema di GPS/IMU coordinate (come OXTS nel set di dati open source AV KITTI), è necessario trasformare l'origine in un sistema di coordinate mondiale (in genere il sistema di coordinate di riferimento del veicolo). È possibile applicare questa trasformazione moltiplicando i dati con i parametri di trasformazione (matrice di rotazione e vettore di traslazione). Questo trasformerà i dati dal suo sistema di coordinate originale in un sistema di coordinate di riferimento globale. Ulteriori informazioni su questa trasformazione sono disponibili nella sezione successiva.
### Conversione dei dati di nuvole di punti 3D in un WCS
Ground Truth presuppone che i dati della nuvola di punti siano già stati trasformati in un sistema di coordinate di riferimento scelto. Ad esempio, è possibile scegliere il sistema di coordinate di riferimento del sensore (ad esempio LiDAR) come sistema di coordinate di riferimento globale. È inoltre possibile prendere nuvole di punti da vari sensori e trasformarle dalla vista del sensore alla vista del sistema di coordinate di riferimento del veicolo. È possibile utilizzare la matrice estrinseca di un sensore, costituita da una matrice di rotazione e da un vettore di traslazione, per convertire i dati della nuvola di punti in un WCS o un quadro di riferimento globale.
Collettivamente, il vettore di traslazione e la matrice di rotazione possono essere utilizzati per formare una *matrice estrinseca*, che può essere utilizzata per convertire i dati da un sistema di coordinate locale a un WCS. Ad esempio, la matrice estrinseca LiDAR può essere composta come segue, dove `R` è la matrice di rotazione e `T` è il vettore di traslazione:
```
LiDAR_extrinsic = [R T;0 0 0 1]
```
Ad esempio, il set di dati KITTI a guida autonoma include una matrice di rotazione e un vettore di traslazione per la matrice di trasformazione estrinseca LiDAR per ogni frame. Il modulo Python [pykitti](https://github.com/utiasSTARS/pykitti) può essere utilizzato per caricare i dati KITTI e, nel set di dati `dataset.oxts[i].T_w_imu` genera la trasformazione estrinseca LiDAR per il `i`° frame che può essere moltiplicato con i punti in quel frame per convertirli in un frame mondiale: `np.matmul(lidar_transform_matrix, points)`. Se un punto nel frame LiDAR viene moltiplicato per una matrice estrinseca LiDAR, si trasforma in coordinate mondiali. Moltiplicando un punto nel frame mondiale con la matrice estrinseca della telecamera, si ottengono le coordinate del punto nel frame di riferimento della telecamera.
Nell'esempio di codice seguente viene illustrato come convertire i frame di nuvole di punti dal set di dati KITTI in un WCS.
```
import pykitti
import numpy as np
basedir = '/Users/nameofuser/kitti-data'
date = '2011_09_26'
drive = '0079'
# The 'frames' argument is optional - default: None, which loads the whole dataset.
# Calibration, timestamps, and IMU data are read automatically.
# Camera and velodyne data are available via properties that create generators
# when accessed, or through getter methods that provide random access.
data = pykitti.raw(basedir, date, drive, frames=range(0, 50, 5))
# i is frame number
i = 0
# lidar extrinsic for the ith frame
lidar_extrinsic_matrix = data.oxts[i].T_w_imu
# velodyne raw point cloud in lidar scanners own coordinate system
points = data.get_velo(i)
# transform points from lidar to global frame using lidar_extrinsic_matrix
def generate_transformed_pcd_from_point_cloud(points, lidar_extrinsic_matrix):
tps = []
for point in points:
transformed_points = np.matmul(lidar_extrinsic_matrix, np.array([point[0], point[1], point[2], 1], dtype=np.float32).reshape(4,1)).tolist()
if len(point) > 3 and point[3] is not None:
tps.append([transformed_points[0][0], transformed_points[1][0], transformed_points[2][0], point[3]])
return tps
# customer transforms points from lidar to global frame using lidar_extrinsic_matrix
transformed_pcl = generate_transformed_pcd_from_point_cloud(points, lidar_extrinsic_matrix)
```
## Fusione dei sensori
Ground Truth supporta la fusione dei sensori dei dati della nuvola di punti con un massimo di 8 ingressi di videocamere. Questa funzione consente agli etichettatori umani di visualizzare la cornice della nuvola di punti 3D side-by-side con la cornice video sincronizzata. Oltre a fornire un contesto visivo più ampio per l'etichettatura, la fusione dei sensori consente ai worker di regolare le annotazioni nella scena 3D e nelle immagini 2D e la regolazione viene proiettata nell'altra vista. Il video seguente mostra un processo di etichettatura di nuvole di punti 3D con LiDAR e fusione dei sensori della telecamera.
![\[GIF che mostra un processo di etichettatura in una nuvola di punti 3D con LiDAR e la fusione dei sensori della telecamera.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/pointcloud/gifs/object_tracking/sensor-fusion.gif)
Per ottenere risultati ottimali, quando si utilizza la fusione di sensori, la nuvola di punti deve trovarsi in un WCS. Ground Truth utilizza le informazioni sulla posizione del sensore (come LiDAR), della telecamera e del veicolo ego per calcolare le matrici estrinseche e intrinseche per la fusione dei sensori.
### Matrice estrinseca
Ground Truth utilizza matrici estrinseche del sensore (come LiDAR) ed estrinseche e intrinseche della telecamera per proiettare oggetti da e verso il frame di riferimento dei dati della nuvola di punti al frame di riferimento della telecamera.
Ad esempio, per proiettare un'etichetta dalla nuvola di punti 3D al piano dell'immagine della telecamera, Ground Truth trasforma i punti 3D dal sistema di coordinate LiDAR al sistema di coordinate della telecamera. Ciò avviene in genere trasformando prima i punti 3D del sistema di coordinate LiDAR in un sistema di coordinate mondiale (o un quadro di riferimento globale) utilizzando la matrice estrinseca LiDAR. Ground Truth utilizza quindi l'estrinseco inverso della telecamera (che converte i punti da un quadro di riferimento globale al quadro di riferimento della telecamera) per trasformare i punti 3D del sistema di coordinate mondiali ottenuto nella fase precedente nel piano dell'immagine della telecamera. La matrice estrinseca LiDAR può anche essere utilizzata per trasformare i dati 3D in un sistema di coordinate mondiali. Se i dati 3D sono già trasformati in un sistema di coordinate mondiali, la prima trasformazione non ha alcun impatto sulla traslazione delle etichette e la traslazione delle etichette dipende solo dall'estrinseca inversa della telecamera. Una matrice di viste viene utilizzata per visualizzare le etichette proiettate. Per ulteriori informazioni su queste trasformazioni e sulla matrice della visualizzazione, consulta [Trasformazioni della fusione dei sensori Ground Truth](#sms-point-cloud-extrinsic-intrinsic-explanation).
Ground Truth calcola queste matrici estrinseche utilizzando LiDAR e i *dati di posizione* della telecamera forniti dall'utente: `heading` (in quaternioni: `qx`, `qy`, `qz` e `qw`) e `position` (`x`, `y`, `z`). Per il veicolo, tipicamente la direzione e la posizione sono descritte nel quadro di riferimento del veicolo in un sistema di coordinate mondiali e sono chiamate *posa di un veicolo ego*. Per ogni telecamera estrinseca, è possibile aggiungere informazioni sulla posa per quella telecamera. Per ulteriori informazioni, consulta [Posa](#sms-point-cloud-pose).
### Matrice intrinseca
Ground Truth utilizza le matrici estrinseche e intrinseche della telecamera per calcolare i parametri di visualizzazione per trasformare le etichette da e verso la scena 3D alle immagini della telecamera. Ground Truth calcola la matrice intrinseca della telecamera utilizzando la lunghezza focale della stessa (`fx`, `fy`) e le coordinate del centro ottico (`cx`, `cy`) fornite dall'utente. Per ulteriori informazioni, consulta [Intrinseca e distorsione](#sms-point-cloud-camera-intrinsic-distortion).
### Distorsione immagine
La distorsione dell'immagine può verificarsi per una serie di motivi. Ad esempio, le immagini possono essere distorte a causa degli effetti barile o fish-eye. Ground Truth utilizza parametri intrinsechi insieme al coefficiente di distorsione per non distorcere le immagini fornite durante la creazione di processi di etichettatura con nuvole di punti 3D. Se la distorsione di un'immagine della telecamera è già stata annullata, tutti i coefficienti di distorsione devono essere impostati su 0.
Per ulteriori informazioni sulle trasformazioni eseguite da Ground Truth per annullare la distorsione delle immagini, consulta [Calibrazioni telecamera: estrinseca, intrinseca e distorsione](#sms-point-cloud-extrinsic-camera-explanation).
### Veicolo Ego
Per raccogliere dati per applicazioni di guida autonome, le misurazioni utilizzate per generare dati di nuvole di punti vengono prese da sensori montati su un veicolo o sul *veicolo ego*. Per proiettare le regolazioni delle etichette da e verso la scena 3D e le immagini 2D, Ground Truth richiede che il veicolo ego si trovi in un sistema di coordinate mondiali. La posizione del veicolo ego comprende coordinate di posizione e quaternione di orientamento.
Ground Truth usa la posa del veicolo ego per calcolare le matrici di rotazione e le trasformazioni. Le rotazioni in 3 dimensioni possono essere rappresentate da una sequenza di 3 rotazioni intorno a una sequenza di assi. In teoria, tre assi che attraversano lo spazio euclideo 3D sono sufficienti. In pratica, gli assi di rotazione sono scelti come vettori di base. Si prevede che le tre rotazioni rientrino in un sistema di riferimento globale (estrinseco). Ground Truth non ha un sistema di riferimento (intrinseco) centrato sul corpo di supporto che è collegato all’oggetto in rotazione e si muove con esso. Per tracciare gli oggetti, Ground Truth deve misurare da un riferimento globale in cui tutti i veicoli sono in movimento. Quando si utilizzano processi di etichettatura di nuvole di punti Ground Truth 3D, z specifica l'asse di rotazione (rotazione estrinseca) e gli angoli di Eulero di imbardata sono espressi in radianti (angolo di rotazione).
### Posa
Ground Truth utilizza le informazioni di posa per le visualizzazioni 3D e la fusione dei sensori. Le informazioni di posa inserite attraverso il file manifest vengono utilizzate per calcolare matrici estrinseche. Se si dispone già di una matrice estrinseca, è possibile utilizzarla per estrarre i dati del sensore e della posa della telecamera.
Ad esempio nel dataset KITTI a guida autonoma, il modulo Python [pykitti](https://github.com/utiasSTARS/pykitti) può essere utilizzato per caricare i dati KITTI. Nel set di dati `dataset.oxts[i].T_w_imu` fornisce la trasformazione estrinseca LiDAR per il `i`° frame e può essere moltiplicato con i punti per inserirli in un frame mondiale - `matmul(lidar_transform_matrix, points)`. Questa trasformazione può essere convertita in posizione (vettore di traslazione) e intestazione (in quaternione) di LiDAR per il formato JSON del file manifest di input. La trasformazione estrinseca della telecamera per `cam0` nel `i`° frame può essere calcolata da `inv(matmul(dataset.calib.T_cam0_velo, inv(dataset.oxts[i].T_w_imu)))` e questo può essere convertito in titolo e posizione per `cam0`.
```
import numpy
rotation = [[ 9.96714314e-01, -8.09890350e-02, 1.16333982e-03],
[ 8.09967396e-02, 9.96661051e-01, -1.03090934e-02],
[-3.24531964e-04, 1.03694477e-02, 9.99946183e-01]]
origin= [1.71104606e+00,
5.80000039e-01,
9.43144935e-01]
from scipy.spatial.transform import Rotation as R
# position is the origin
position = origin
r = R.from_matrix(np.asarray(rotation))
# heading in WCS using scipy
heading = r.as_quat()
print(f"pose:{position}\nheading: {heading}")
```
**Position**
Nel file manifest di input, `position` si riferisce alla posizione del sensore rispetto a un frame mondiale. Se non si riesce a inserire la posizione del dispositivo in un sistema di coordinate mondiali, è possibile utilizzare i dati LiDAR con coordinate locali. Allo stesso modo, per le videocamere montate è possibile specificare la posizione e l'intestazione in un sistema di coordinate mondiali. Per la telecamera, se non si dispone di informazioni sulla posizione, utilizzare (0, 0, 0).
Di seguito sono riportati i campi nell'oggetto posizione:
1. `x` (in virgola mobile): coordinata x del veicolo ego, del sensore o della posizione della telecamera in metri.
1. `y` (in virgola mobile): coordinata y del veicolo ego, del sensore o della posizione della telecamera in metri.
1. `z` (in virgola mobile): coordinata z del veicolo ego, del sensore o della posizione della telecamera in metri.
Di seguito è riportato un esempio di un oggetto JSON `position`:
```
{
"position": {
"y": -152.77584902657554,
"x": 311.21505956090624,
"z": -10.854137529636024
}
}
```
**Heading**
Nel file manifest di input, `heading` è un oggetto che rappresenta l'orientamento di un dispositivo rispetto al frame mondiale. I valori delle intestazioni devono essere in quaternione. Un [quaternione](https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation) è una rappresentazione dell'orientamento coerente con le proprietà sferiche geodesiche. Se non riesci a inserire l'intestazione del sensore nelle coordinate mondiali, usa il quaternione dell'identità `(qx = 0, qy = 0, qz = 0, qw = 1)`. Allo stesso modo, per le telecamere, specifica l'intestazione in quaternioni. Se non riesci a ottenere parametri estrinseci di calibrazione della telecamera, utilizza anche il quaternione di identità.
I campi nell'oggetto `heading` sono i seguenti:
1. `qx` (in virgola mobile): componente x del veicolo ego, del sensore o dell'orientamento della telecamera.
1. `qy` (in virgola mobile): componente y del veicolo ego, del sensore, o dell'orientamento della telecamera.
1. `qz` (in virgola mobile): componente z del veicolo ego, del sensore o dell'orientamento della telecamera.
1. `qw` (in virgola mobile): componente w del veicolo ego, del sensore o dell'orientamento della telecamera.
Di seguito è riportato un esempio di un oggetto JSON `heading`:
```
{
"heading": {
"qy": -0.7046155108831117,
"qx": 0.034278837280808494,
"qz": 0.7070617895701465,
"qw": -0.04904659893885366
}
}
```
Per ulteriori informazioni, consulta [Calcolo dei quaternioni e della posizione di orientamento](#sms-point-cloud-ego-vehicle-orientation).
## Calcolo dei quaternioni e della posizione di orientamento
Ground Truth richiede che tutti i dati di orientamento, o intestazione, siano forniti in quaternioni. Un [quaternione](https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation) è una rappresentazione dell'orientamento coerente con proprietà sferiche geodesiche che possono essere utilizzate per approssimare la rotazione. Rispetto agli [angoli di Eulero](https://en.wikipedia.org/wiki/Euler_angles) sono più semplici da comporre ed evitano il problema del [blocco cardanico](https://en.wikipedia.org/wiki/Gimbal_lock). Rispetto alle matrici di rotazione sono più compatti, più stabili numericamente e più efficienti.
È possibile calcolare quaternioni da una matrice di rotazione o da una matrice di trasformazione.
Se si dispone di una matrice di rotazione (composta dalle rotazioni degli assi) e vettore di traslazione (o origine) nel sistema di coordinate mondiali invece di una singola matrice di trasformazione rigida 4x4, è possibile utilizzare direttamente la matrice di rotazione e il vettore di traslazione per calcolare i quaternioni. Librerie come [scipy](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.html) e [pyqaternion ](http://kieranwynn.github.io/pyquaternion/#explicitly-by-rotation-or-transformation-matrix) possono aiutare. Il seguente blocco di codice mostra un esempio che utilizza queste librerie per calcolare il quaternione da una matrice di rotazione.
```
import numpy
rotation = [[ 9.96714314e-01, -8.09890350e-02, 1.16333982e-03],
[ 8.09967396e-02, 9.96661051e-01, -1.03090934e-02],
[-3.24531964e-04, 1.03694477e-02, 9.99946183e-01]]
origin = [1.71104606e+00,
5.80000039e-01,
9.43144935e-01]
from scipy.spatial.transform import Rotation as R
# position is the origin
position = origin
r = R.from_matrix(np.asarray(rotation))
# heading in WCS using scipy
heading = r.as_quat()
print(f"position:{position}\nheading: {heading}")
```
Anche uno strumento UI come il [3D Rotation Converter](https://www.andre-gaschler.com/rotationconverter/) può essere utile.
Se si dispone di una matrice di trasformazione estrinseca 4x4, si noti che la matrice di trasformazione è nel formato `[R T; 0 0 0 1]` dove `R` è la matrice di rotazione e `T` è il vettore di traslazione dell'origine. Ciò significa che è possibile estrarre la matrice di rotazione e il vettore di traslazione dalla matrice di trasformazione come segue.
```
import numpy as np
transformation
= [[ 9.96714314e-01, -8.09890350e-02, 1.16333982e-03, 1.71104606e+00],
[ 8.09967396e-02, 9.96661051e-01, -1.03090934e-02, 5.80000039e-01],
[-3.24531964e-04, 1.03694477e-02, 9.99946183e-01, 9.43144935e-01],
[ 0, 0, 0, 1]]
transformation = np.array(transformation )
rotation = transformation[0:3,0:3]
translation= transformation[0:3,3]
from scipy.spatial.transform import Rotation as R
# position is the origin translation
position = translation
r = R.from_matrix(np.asarray(rotation))
# heading in WCS using scipy
heading = r.as_quat()
print(f"position:{position}\nheading: {heading}")
```
Con la tua configurazione, puoi calcolare una matrice di trasformazione estrinseca utilizzando la GPS/IMU posizione e l'orientamento (latitudine, longitudine, altitudine e rollio, inclinazione, imbardata) rispetto al sensore LiDAR sul veicolo ego. Ad esempio, è possibile calcolare la posa dai dati grezzi KITTI utilizzando `pose = convertOxtsToPose(oxts)` per trasformare i dati oxts in pose euclidee locali, specificate da matrici di trasformazione rigide 4x4. Puoi quindi trasformare questa matrice di trasformazione posa in un frame di riferimento globale utilizzando la matrice di trasformazione dei frame di riferimento nel sistema di coordinate mondiali.
```
struct Quaternion
{
double w, x, y, z;
};
Quaternion ToQuaternion(double yaw, double pitch, double roll) // yaw (Z), pitch (Y), roll (X)
{
// Abbreviations for the various angular functions
double cy = cos(yaw * 0.5);
double sy = sin(yaw * 0.5);
double cp = cos(pitch * 0.5);
double sp = sin(pitch * 0.5);
double cr = cos(roll * 0.5);
double sr = sin(roll * 0.5);
Quaternion q;
q.w = cr * cp * cy + sr * sp * sy;
q.x = sr * cp * cy - cr * sp * sy;
q.y = cr * sp * cy + sr * cp * sy;
q.z = cr * cp * sy - sr * sp * cy;
return q;
}
```
## Trasformazioni della fusione dei sensori Ground Truth
Le sezioni seguenti illustrano in modo più dettagliato le trasformazioni di fusione dei sensori Ground Truth eseguite utilizzando i dati di posa forniti.
### LiDAR estrinseco
Per proiettare da e verso una scena LiDAR 3D su un'immagine di una telecamera 2D, Ground Truth calcola le rigide metriche di proiezione della trasformazione utilizzando la posizione e la direzione del veicolo ego. Ground Truth calcola la rotazione e la traslazione delle coordinate di un mondo nel piano 3D eseguendo una semplice sequenza di rotazioni e traslazioni.
Ground Truth calcola i parametri di rotazione utilizzando i quaternioni di intestazione come segue:
![\[Equazione: metriche di rotazione in una nuvola di punti Ground Truth.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/pointcloud/sms-point-cloud-rotation-matrix.png)
Qui, `[x, y, z, w]` corrisponde ai parametri dell'oggetto JSON `heading` `[qx, qy, qz, qw]`. Ground Truth calcola il vettore della colonna di traduzione come `T = [poseX, poseY, poseZ]`. Quindi, i parametri estrinseci sono semplicemente i seguenti:
```
LiDAR_extrinsic = [R T;0 0 0 1]
```
### Calibrazioni telecamera: estrinseca, intrinseca e distorsione
La *calibrazione geometrica della telecamera*, detta anche *resezionamento della telecamera*, stima i parametri di un obiettivo e di un sensore di immagine di un'immagine o di una telecamera. È possibile utilizzare questi parametri per correggere la distorsione dell'obiettivo, misurare la dimensione di un oggetto in unità mondiali o determinare la posizione della telecamera nella scena. I parametri della telecamera includono i coefficienti intrinseci e di distorsione.
#### Telecamera estrinseca
Se viene data la posa della telecamera, Ground Truth calcola la telecamera estrinseca in base a una rigida trasformazione dal piano 3D al piano della telecamera. Il calcolo è lo stesso di quello utilizzato per [LiDAR estrinseco](#sms-point-cloud-extrinsic-lidar-explanation), tranne che per il fatto che Ground Truth utilizza la posa della telecamera (`position` e `heading`) e calcola l'estrinseca inversa.
```
camera_inverse_extrinsic = inv([Rc Tc;0 0 0 1]) #where Rc and Tc are camera pose components
```
#### Intrinseca e distorsione
Alcune telecamere, come le telecamere stenopeiche o fisheye, possono introdurre una distorsione significativa nelle foto. Questa distorsione può essere corretta utilizzando i coefficienti di distorsione e la lunghezza focale della telecamera. Per ulteriori informazioni, vedi [Calibrazione della telecamera con OpenCV](https://docs.opencv.org/2.4.13.7/doc/tutorials/calib3d/camera_calibration/camera_calibration.html) nella documentazione di OpenCV.
Ci sono due tipi di distorsione che Ground Truth può correggere: la distorsione radiale e la distorsione tangenziale.
La *distorsione radiale* si verifica quando i raggi di luce si piegano più vicino ai bordi di un obiettivo rispetto al suo centro ottico. Più piccolo è l'obiettivo, maggiore è la distorsione. La presenza della distorsione radiale si manifesta sotto forma di effetto *barile* o *fish-eye* e Ground Truth utilizza la Formula 1 per non distorcerla.
**Formula 1:**
![\[Formula 1: equazioni per x_{corrected} e y_{corrected}, per correggere la distorsione radiale.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/pointcloud/sms-point-cloud-camera-distortion-1.png)
La *distorsione tangenziale* si verifica perché gli obiettivi utilizzati per riprendere le immagini non sono perfettamente paralleli al piano di imaging. Questo può essere corretto con la Formula 2.
**Formula 2:**
![\[Formula 2: equazioni per x_{corrected} e y_{corrected}, per correggere la distorsione tangenziale.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/pointcloud/sms-point-cloud-camera-distortion-2.png)
Nel file manifest di input, è possibile fornire coefficienti di distorsione e Ground Truth eliminerà la distorsione delle immagini. Tutti i coefficienti di distorsione sono in virgola mobile.
+ `k1`, `k2`, `k3`, `k4`: coefficienti di distorsione radiale. Supportato sia per i modelli di fotocamere fisheye e a foro stenopeico.
+ `p1` , `p2`: coefficienti di distorsione tangenziale. Supportato per i modelli di fotocamera a foro stenopeico.
Se la distorsione delle immagini è già stata eliminata, tutti i coefficienti di distorsione dovrebbero essere 0 nel manifest di input.
Al fine di ricostruire correttamente l'immagine esatta, Ground Truth fa una conversione delle unità delle immagini in base alle lunghezze focali. Se si utilizza una lunghezza focale comune con un dato rapporto di aspetto per entrambi gli assi, ad esempio 1, nella formula superiore avremo una singola lunghezza focale. La matrice contenente questi quattro parametri è indicata come *matrice di calibrazione intrinseca della telecamera*.
![\[L’array di calibrazione intrinseca della telecamera.\]](http://docs.aws.amazon.com/it_it/sagemaker/latest/dg/images/pointcloud/sms-point-cloud-camera-intrinsic.png)
Sebbene i coefficienti di distorsione siano gli stessi indipendentemente dalle risoluzioni della telecamera utilizzate, questi dovrebbero essere scalati con la risoluzione corrente rispetto alla risoluzione calibrata.
Di seguito sono riportati i valori in virgola mobile.
+ `fx`: lunghezza focale in direzione x.
+ `fy`: lunghezza focale in direzione y.
+ `cx`: coordinata x del punto principale.
+ `cy`: coordinata y del punto principale.
Ground Truth utilizza la telecamera estrinseca e intrinseca per calcolare i parametri della vista, come mostrato nel seguente blocco di codice per trasformare le etichette tra la scena 3D e le immagini 2D.
```
def generate_view_matrix(intrinsic_matrix, extrinsic_matrix):
intrinsic_matrix = np.c_[intrinsic_matrix, np.zeros(3)]
view_matrix = np.matmul(intrinsic_matrix, extrinsic_matrix)
view_matrix = np.insert(view_matrix, 2, np.array((0, 0, 0, 1)), 0)
return view_matrix
```