> This page is for Plataforma, version Herdado. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Herdado: 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. # Trabalhar com anotações # Visão geral As anotações no Frame.io são representadas como um blob JSON serializado de objetos de desenho, incluindo cores, coordenadas e tamanhos.No blob, todas as aspas, exceto o par delimitador externo, são escapadas com barras invertidas (ex.: `\"key\":\"value\"`).Há três formas básicas: **arrow**, **rect** e **line**, além do desenho à mão livre, que está fora do escopo deste guia, mas segue os mesmos princípios básicos de dados de coordenadas serializados. ## O sistema de coordenadas Todas as formas são colocadas em um sistema de coordenadas cartesianas com uma origem superior esquerda e uma escala de 0 a 1 em cada eixo. coordinate_plane.png ## Dados básicos de forma Todas as formas são colocadas no plano acima com uma combinação de coordenadas e dados de estilo.Cada forma possui alguns atributos em comum, mas cada uma tem uma maneira ligeiramente diferente de se relacionar com o sistema de coordenadas. Todos os atributos para distância/largura/altura usam a mesma escala de 0 a 1 que a própria grade de coordenadas principal, mas geralmente são marcados a partir do ponto de origem da forma. Em outras palavras, se um vídeo está sendo exibido em uma janela de visualização de 640x480, `x=1` será igual a 640px absolutos nesse contexto.Isso permite que as anotações sejam dimensionadas perfeitamente mantendo sua posição relativa conforme a tela de visualização, o tamanho e o contexto mudam.**Observação**: a origem de um *rect* é sempre o canto superior esquerdo da forma, independentemente da origem do desenho. ### Atributos comuns | Atributo | Descrição | | ---------- | ---------- | | `tool` | *arrow*, *rect* ou *line*.Declara qual forma está sendo criada. | | `color` | Código de cor hexadecimal de seis dígitos para a forma. | | `size` | Tamanho em pixels para a linha da forma.Para setas, isso se refere apenas ao início da linha, pois a largura final é determinada programaticamente. | ### Arrow | Atributo | Descrição | |:--------|:----------| | `x` | coordenada x da origem da seta. | | `y` | coordenada y da origem da seta. | | `w` | Diferença na posição do eixo y da seta do início ao fim, relativa à origem da seta. | | `h` | Diferença na posição do eixo x da seta do início ao fim, relativa à origem da seta. | ### Rect | Atributo | Descrição | |:--------|:----------| | `x` | coordenada x do canto superior esquerdo do retângulo. | | `y` | coordenada y do canto superior esquerdo do retângulo. | | `w` | Largura do retângulo, relativa à origem do retângulo superior esquerdo. | | `h` | Altura do retângulo, relativa à origem do retângulo superior esquerdo. | | `ix` | A origem x do desenho do retângulo.(Não obrigatório). | | `iy` | A origem y do desenho do retângulo.(Não obrigatório). | | `radius` | Raio do arredondamento do canto do retângulo.Deve ser positivo.Valores acima de 150 são visualmente indistinguíveis. | ### Line | Atributo | Descrição | |:--------|:----------| | `x1` | coordenada x da origem da linha. | | `y1` | coordenada y da origem da linha. | | `x2` | coordenada x do término da linha.Valor absoluto no plano da imagem. | | `y2` | coordenada y do término da linha.Valor absoluto no plano da imagem. | ## Exemplo simples: o plano de coordenadas 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 } ] } ``` ### Detalhamento 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 } ``` ## Exemplo complexo: muitas caixas 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 } ] } ``` ### Detalhamento Com tudo isso em mente, é útil dispor cada elemento na imagem acima para desenvolver uma imagem mais clara do sistema de coordenadas de anotação.Observe que `size` e `radius` para cada um dos retângulos neste exemplo estão usando os padrões da interface do usuário Frame.io. #### Retângulo azul 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 } ``` #### Retângulo 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 } ``` #### Retângulo vermelho 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 } ``` #### Retângulo laranja 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 } ``` #### Seta vermelha red-arrow.png ```json { "tool":"arrow", "color":"#E74A3C", "size":3, "x":0.25374531835205993, "y":0.23137744486059092, "w":0.24250936329588013, "h":0 } ```