> This page is for Piattaforma, version Versione precedente. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Versione precedente: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Lavorare con le annotazioni # Panoramica Le annotazioni in Frame.io sono rappresentate come un blob JSON serializzato di oggetti di disegno, completi di colori, coordinate e dimensioni. Nel blob, tutte le virgolette tranne la coppia di delimitazione esterna sono precedute da barre oblique (ad esempio `\"key\":\"value\"`). Esistono tre forme di base (**arrow**, **rect** e **line**), oltre al disegno a mano libera, che esula dall'ambito di questa guida, ma segue gli stessi principi di base dei dati di coordinate serializzati. ## Il sistema di coordinate Tutte le forme sono posizionate su un sistema di coordinate cartesiano con origine in alto a sinistra e una scala da 0 a 1 su ciascun asse. coordinate_plane.png ## Dati di forma di base Tutte le forme sono posizionate sul piano sopra riportato con una combinazione di coordinate e dati di stile. Ogni forma ha alcuni attributi comuni e ognuna ha un modo leggermente diverso di gestire il sistema di coordinate. Tutti gli attributi per distanza, larghezza e altezza utilizzano la stessa scala da 0 a 1 della griglia di coordinate principale, ma sono generalmente contrassegnati dal punto di origine della forma. In altre parole, se un video viene mostrato in una finestra di visualizzazione 640x480, `x=1` corrisponderà a 640 px assoluti in quel contesto. Questo consente alle annotazioni di adattarsi senza problemi mantenendo la loro posizione relativa quando schermo di visualizzazione, dimensioni e contesto cambiano. **Nota**: l'origine di un *rect* è sempre l'angolo superiore sinistro della forma, indipendentemente dall'origine del disegno. ### Attributi comuni | Attributo | Descrizione | | ---------- | ---------- | | `tool` | *arrow*, *rect* o *line*. Indica quale forma viene creata. | | `color` | Colore esadecimale a sei cifre per la forma. | | `size` | Dimensione in pixel per la linea della forma. Per le frecce, si riferisce solo all'inizio della linea, poiché la larghezza finale è determinata programmaticamente. | ### Freccia | Attributo | Descrizione | |:--------|:----------| | `x` | Coordinata x dell'origine della freccia. | | `y` | Coordinata y dell'origine della freccia. | | `w` | Differenza nella posizione dell'asse y della freccia dall'inizio alla fine, relativa all'origine della freccia. | | `h` | Differenza nella posizione dell'asse x della freccia dall'inizio alla fine, relativa all'origine della freccia. | ### Rettangolo | Attributo | Descrizione | |:--------|:----------| | `x` | Coordinata x dell'angolo superiore sinistro del rettangolo. | | `y` | Coordinata y dell'angolo superiore sinistro del rettangolo. | | `w` | Larghezza del rettangolo, relativa all'origine del rettangolo superiore sinistro. | | `h` | Altezza del rettangolo, relativa all'origine del rettangolo superiore sinistro. | | `ix` | L'origine x del disegno del rettangolo (non richiesta). | | `iy` | L'origine y del disegno del rettangolo (non richiesta). | | `radius` | Raggio dell'arrotondamento degli angoli del rettangolo. Deve essere un numero positivo. I valori superiori a 150 sono visivamente indistinguibili. | ### Linea | Attributo | Descrizione | |:--------|:----------| | `x1` | Coordinata x dell'origine della linea. | | `y1` | Coordinata y dell'origine della linea. | | `x2` | Coordinata x del termine della linea. Valore assoluto sul piano dell'immagine. | | `y2` | Coordinata y del termine della linea. Valore assoluto sul piano dell'immagine. | ## Esempio semplice: il piano delle coordinate plane-example.png ```serialized {"annotation": "[{\"tool\":\"line\",\"color\":\"#E74A3C\",\"size\":3,\"x1\":0.0028530670470756064,\"y1\":0.012680297987002695,\"x2\":0.9964336661911555,\"y2\":0.9903312727849104},{\"tool\":\"line\",\"color\":\"#34A3DB\",\"size\":3,\"x1\":0.004992867332382311,\"y1\":0.98779521318751,\"x2\":0.9942938659058488,\"y2\":0.012680297987002695}]} ``` ```json { "annotation": [ { "tool": "line", "color": "#E74A3C", "size": 3, "x1": 0.0028530670470756064, "y1": 0.012680297987002695, "x2": 0.9964336661911555, "y2": 0.9903312727849104 }, { "tool": "line", "color": "#34A3DB", "size": 3, "x1": 0.004992867332382311, "y1": 0.98779521318751, "x2": 0.9942938659058488, "y2": 0.012680297987002695 } ] } ``` ### Suddivisione blue-plane.png ```json { "tool":"line", "color":"#34A3DB", "size":3, "x1":0.004992867332382311, "y1":0.98779521318751, "x2":0.9942938659058488, "y2":0.012680297987002695 } ``` plane-example-red.png ```json { "tool":"line", "color":"#E74A3C", "size":3, "x1":0.0028530670470756064, "y1":0.012680297987002695, "x2":0.9964336661911555, "y2":0.9903312727849104 } ``` ## Esempio complesso: molte caselle lots-of-boxes.png ```serialized {"annotation": "[{\"tool\":\"rect\",\"color\":\"#34A3DB\",\"size\":3,\"x\":0.008426966292134831,\"y\":0.02663337494798169,\"w\":0.0702247191011236,\"h\":0.10986267166042447,\"ix\":0.008426966292134831,\"iy\":0.02663337494798169,\"radius\":8},{\"tool\":\"rect\",\"color\":\"#1ABCA1\",\"size\":3,\"x\":0.8932584269662921,\"y\":0.0449438202247191,\"w\":0.08895131086142327,\"h\":0.35122763212650854,\"ix\":0.8932584269662921,\"iy\":0.0449438202247191,\"radius\":8},{\"tool\":\"rect\",\"color\":\"#E67422\",\"size\":3,\"x\":0.023408239700374533,\"y\":0.7873491468997087,\"w\":0.1254681647940075,\"h\":0.2047440699126093,\"ix\":0.023408239700374533,\"iy\":0.7873491468997087,\"radius\":8},{\"tool\":\"rect\",\"color\":\"#E74A3C\",\"size\":3,\"x\":0.6919475655430711,\"y\":0.5409904286308781,\"w\":0.29868913857677903,\"h\":0.4427798585101955,\"ix\":0.6919475655430711,\"iy\":0.5409904286308781,\"radius\":8},{\"tool\":\"arrow\",\"color\":\"#E74A3C\",\"size\":3,\"x\":0.25374531835205993,\"y\":0.23137744486059092,\"w\":0.24250936329588013,\"h\":0}]}" ``` ```json { "annotation": [ { "tool": "rect", "color": "#34A3DB", "size": 3, "x": 0.008426966292134831, "y": 0.02663337494798169, "w": 0.0702247191011236, "h": 0.10986267166042447, "ix": 0.008426966292134831, "iy": 0.02663337494798169, "radius": 8 }, { "tool": "rect", "color": "#1ABCA1", "size": 3, "x": 0.8932584269662921, "y": 0.0449438202247191, "w": 0.08895131086142327, "h": 0.35122763212650854, "ix": 0.8932584269662921, "iy": 0.0449438202247191, "radius": 8 }, { "tool": "rect", "color": "#E67422", "size": 3, "x": 0.023408239700374533, "y": 0.7873491468997087, "w": 0.1254681647940075, "h": 0.2047440699126093, "ix": 0.023408239700374533, "iy": 0.7873491468997087, "radius": 8 }, { "tool": "rect", "color": "#E74A3C", "size": 3, "x": 0.6919475655430711, "y": 0.5409904286308781, "w": 0.29868913857677903, "h": 0.4427798585101955, "ix": 0.6919475655430711, "iy": 0.5409904286308781, "radius": 8 }, { "tool": "arrow", "color": "#E74A3C", "size": 3, "x": 0.25374531835205993, "y": 0.23137744486059092, "w": 0.24250936329588013, "h": 0 } ] } ``` ### Suddivisione Tenendo presente tutto questo, è utile stabilire la disposizione di ogni elemento nell'immagine mostrata in alto per sviluppare un quadro più chiaro del sistema di coordinate delle annotazioni. Tieni presente che `size` e `radius` per ciascuno dei rettangoli in questo esempio utilizzano le impostazioni predefinite dell'interfaccia utente di Frame.io. #### Rettangolo blu blue-box.png ```json { "tool":"rect", "color":"#34A3DB", "size":3, "x":0.008426966292134831, "y":0.02663337494798169, "w":0.0702247191011236, "h":0.10986267166042447, "ix":0.008426966292134831, "iy":0.02663337494798169, "radius":8 } ``` #### Rettangolo verde box-green.png ```json { "tool":"rect", "color":"#1ABCA1", "size":3, "x":0.8932584269662921, "y":0.0449438202247191, "w":0.08895131086142327, "h":0.35122763212650854, "ix":0.8932584269662921, "iy":0.0449438202247191, "radius":8 } ``` #### Rettangolo rosso red-box.png ```json { "tool":"rect", "color":"#E74A3C", "size":3, "x":0.6919475655430711, "y":0.5409904286308781, "w":0.29868913857677903, "h":0.4427798585101955, "ix":0.6919475655430711, "iy":0.5409904286308781, "radius":8 } ``` #### Rettangolo arancione orange-box.png ```json { "tool":"rect", "color":"#E67422", "size":3, "x":0.023408239700374533, "y":0.7873491468997087, "w":0.1254681647940075, "h":0.2047440699126093, "ix":0.023408239700374533, "iy":0.7873491468997087, "radius":8 } ``` #### Freccia rossa red-arrow.png ```json { "tool":"arrow", "color":"#E74A3C", "size":3, "x":0.25374531835205993, "y":0.23137744486059092, "w":0.24250936329588013, "h":0 } ```