# Formato de cena 3D

> Como é um plano de cena 3D do Nodaro: primitivas e quadros-chave na versão 1; assets GLB, entidades, trilha de câmera, tomadas e sobreposições na versão 2.

Source: https://nodaro.ai/pt-BR/docs/developers/embed/scene3d-format

Um **plano de cena 3D** é o dado que o Nodaro armazena para uma cena 3D editável: uma composição com `planType: "3d-scene"` e um `schemaVersion` explícito. Os jobs de [**Gerar cena 3D** (Generate 3D Scene)](https://nodaro.ai/docs/nodes/video/generate-3d-scene) e de [**Editar cena 3D** (Edit 3D Scene)](https://nodaro.ai/docs/nodes/video/edit-3d-scene) retornam um plano em `output_data.scenePlan`. O [**Renderizar vídeo** (Render Video)](https://nodaro.ai/docs/nodes/video/render-video) transforma um plano em MP4, e o [viewport de cena 3D](https://nodaro.ai/docs/developers/embed/scene3d) desenha um plano. Esta página explica como um plano é organizado, para que o seu código possa armazenar, validar, mostrar e editar planos.

## Regras para todas as versões
- **Unidades e eixos.** As posições são em metros, em um sistema de coordenadas destro, com o eixo Y para cima. As rotações de Euler são em radianos.
- **Tempo.** Os quadros são numerados a partir de zero. Uma cena dura de 1 a 60 segundos, com 15 a 60 quadros por segundo; o padrão é 4 segundos a 24 fps.
- **Revisões.** Todo plano tem um `revisionId`. Uma edição nunca altera um plano: ela cria uma nova revisão cujo `parentRevisionId` é a revisão de origem. Cada MP4 renderizado usa uma revisão exata.
- **Versões.** Leia `schemaVersion` antes de ler qualquer campo que pertença a uma versão. A versão 1 descreve geometria primitiva; a versão 2 acrescenta geometria pré-calculada (baked) e tomadas.
- **Descoberta.** `GET /v1/3d-scene/capabilities` informa quais mecanismos de criação, e portanto quais versões de cena, uma implantação aceita. Os mecanismos opcionais dependem da configuração da implantação. O mecanismo padrão, o Básico, produz a versão 1.

## Tipos e schemas
O pacote `@nodaro/shared` exporta os tipos e os validadores:

| Exportação | O que é |
| --- | --- |
| `Scene3DPlanV1`, `Scene3DPlanV2` | O tipo de cada versão. |
| `Scene3DPlan` | A união das duas versões. |
| `scene3DAnyPlanSchema` | Um validador que aceita as duas versões. |
| `scene3DPlanSchema` | Um validador só para a versão 1. |
| `scene3DPlanV2Schema` | Um validador só para a versão 2. |

Os validadores verificam a estrutura e as regras entre campos: ciclos de pais, pais ausentes, quadros-chave depois do último quadro e o teto de duração. Um plano que falha é recusado por inteiro.

## Versão 1: primitivas e quadros-chave
Uma cena da versão 1 é autossuficiente. Ela descreve formas primitivas e grupos delimitados, incluindo representações simples de personagens, com quadros-chave esparsos para cada objeto e para a câmera. Ela não reconstrói malhas detalhadas com textura nem simulações físicas.

Um plano da versão 1 armazena:

- os ids, as transformações e as dimensões dos objetos;
- a posição, o alvo e a lente da câmera;
- a iluminação e o fundo;
- os quadros-chave de cada objeto e da câmera.

| Limite | Valor |
| --- | --- |
| Objetos por cena | 100 |
| Quadros-chave por objeto ou por trilha de câmera | 240 |
| Tamanho do id de um objeto | 64 caracteres |
| Largura e altura do quadro | 100 a 2560 px em cada eixo |

### Editar uma cena da versão 1
`POST /v1/3d-scene/edit` recebe um `scenePlan` e um `expectedRevisionId`, além de um `prompt` com uma instrução ou de uma lista de `operations`. Uma revisão divergente é recusada. As operações rodam sem chamar um modelo:

| Operação | Campos |
| --- | --- |
| `set-object` | `objectId` e `changes` em qualquer campo do objeto, exceto o id |
| `add-object` | `object` |
| `remove-object` | `objectId` |
| `set-camera` | `changes` |
| `set-lighting` | `changes` |
| `set-background` | `color` |

Uma operação altera exatamente os campos que você informa. Para alterar uma pose que tem quadros-chave, inclua as alterações dos quadros-chave. A cena editada inteira é validada de novo, então uma edição não pode deixar pais ou referências órfãos. Use `lockedObjectIds` para manter objetos inalterados durante uma edição por instrução. Veja [Editar cena 3D](https://nodaro.ai/docs/nodes/video/edit-3d-scene).

## Versão 2: geometria pré-calculada
Uma cena da versão 2 acrescenta quatro coisas aos conceitos da versão 1:

- **Geometria GLB armazenada,** guardada como assets imutáveis.
- **Entidades semânticas,** as partes nomeadas da cena que os usuários selecionam e editam.
- **Uma trilha de câmera densa,** com uma pose de câmera para cada quadro.
- **Tomadas contíguas,** intervalos de quadros com cortes exatos entre eles.

### Assets
Uma referência de asset da versão 2 contém um `assetId` opaco, um tipo, um papel, um tamanho em bytes e um hash SHA-256. Ela não contém nenhuma credencial de armazenamento nem URL de download.

- Um leitor precisa exatamente dos bytes referenciados. Ele recusa um asset ausente, grande demais ou alterado antes de desenhar qualquer coisa.
- A reprodução carrega a geometria e os dados de câmera. Os arquivos-fonte nativos de uma cena são um download separado, com permissão própria.
- Cada revisão armazenada fixa todos os seus assets, incluindo os bytes que reaproveita de uma revisão anterior.

### Entidades
As entidades semânticas dão nome a raízes na geometria GLB e aos papéis de material dessas raízes, para seleção e edição.

- **Materiais.** Cada papel de material editável indica um material dentro da própria geometria da entidade. O sombreamento de massinha mantém a cor base de cada material, então mudar a pintura da carroceria de um veículo deixa os pneus inalterados.
- **Pais.** Uma entidade pode declarar um pai. A raiz exportada dela fica então aninhada dentro da raiz do pai, e a transformação do nó dela é relativa ao pai. O posicionamento e a animação pré-calculada do pai chegam ao filho pelo próprio arquivo.
- **Concordância.** O plano e o arquivo GLB precisam descrever a mesma hierarquia de pais e filhos. Um leitor recusa uma cena em que os dois divergem.
- **Propriedade.** A geometria, os materiais e a seleção pertencem à entidade que os declara. Mudar a cor de um pai nunca afeta uma entidade aninhada dentro dele.
- **Raízes organizacionais.** Uma entidade pai pode não ter nenhuma geometria e só levar uma transformação pré-calculada, possivelmente animada, para as entidades aninhadas dentro dela. Um leitor a aceita desde que haja algo aninhado ali.

### Âncoras
Uma **âncora** de entidade é um ponto nomeado: um `name` estável e uma `position` no espaço local da entidade.

- Em uma entidade de asset, um `nodeName` opcional vincula a âncora a um nó GLB bruto dentro da própria raiz dessa entidade. A posição e a rotação opcional passam então a usar as coordenadas locais desse nó e acompanham a animação do nó, os ancestrais dele e as edições manuais da entidade.
- Por exemplo, `{ "name": "door.tip", "nodeName": "car/door.hinge", "position": [1, 0, 0] }` coloca um ponto a um metro ao longo do eixo X da dobradiça.
- Um nó ausente, ou um vínculo com uma entidade filha aninhada, é recusado antes da reprodução. As âncoras de primitivas e de grupos ficam no espaço local da entidade.
- Se um mecanismo de criação consegue criar esses vínculos depende do mecanismo.

### Câmera e animação
A trilha de câmera densa contém uma posição, uma rotação e uma projeção para cada quadro. Um leitor mantém esses valores exatamente, incluindo o roll e os cortes exatos entre as tomadas. A animação é amostrada a partir do quadro solicitado, então voltar na linha do tempo e renderizar qualquer quadro isolado dão a mesma pose.

### Visibilidade
A flag opcional `visible` de uma entidade registra a visibilidade pré-calculada dela; quando a flag não existe, a entidade fica visível.

- A geometria oculta continua carregada, e a animação dela continua rodando, então uma sobreposição pode mostrá-la de novo na hora.
- Uma sobreposição tem prioridade sobre o valor pré-calculado, e remover a sobreposição restaura o valor pré-calculado.
- Um pai oculto também oculta tudo o que está aninhado dentro dele.
- Objetos ocultos não recebem cliques na prévia. Use a lista de entidades para selecioná-los e mostrá-los.
- A visibilidade pré-calculada faz parte do hash de conteúdo da revisão.

## Editar uma cena da versão 2 com sobreposições
As edições da versão 2 são **sobreposições** imutáveis acima da cena pré-calculada. Existem quatro tipos: transformação, cor de material, visibilidade e deslocamento de câmera da tomada. Uma sobreposição nunca altera a geometria base nem os bytes da câmera.

- **Uma sobreposição de transformação** se aplica acima do posicionamento pré-calculado da entidade e dos ancestrais dela. O `space` dela diz em qual referencial os valores são lidos:
  - `local` significa o referencial do próprio pai da entidade, com o posicionamento pré-calculado incluído. Os valores ficam constantes nesse referencial, e a edição acompanha um pai em movimento.
  - `world` significa os eixos da cena. Os valores são a posição, a rotação e a escala da entidade no mundo; um ancestral rotacionado, escalado ou animado muda onde a entidade termina, nunca o que os números significam. A entidade continua ligada ao pai, mantém a própria animação pré-calculada, e só os canais que a edição indica ficam fixos.
  - Um leitor recusa o único caso que nenhum dos dois espaços consegue expressar: um ancestral com escala não uniforme sob uma rotação, o que deixa uma transformação que não é uma posição, uma rotação e uma escala.
- **Uma sobreposição de visibilidade** oculta a entidade e tudo o que está aninhado dentro dela. Cada entidade mantém a própria visibilidade, então mostrar o ancestral de novo restaura exatamente os descendentes que não estavam ocultos por conta própria.
- **Toda edição cria uma nova revisão,** com uma revisão pai e um novo hash de conteúdo. Os bloqueios de entidades são respeitados, e uma edição feita sobre uma revisão ou um hash desatualizados é recusada.
- **Os arquivos derivados não são levados adiante.** Pôsteres, relatórios de validação e downloads nativos são gerados de novo para a revisão editada antes de serem anexados a ela.

Para salvar sobreposições sem um job de geração e sem cobrança de LLM, chame `POST /v1/3d-scene/revisions/:revisionId/edits` com um `newRevisionId`, o `expectedContentHash` base, as `operations` e os `lockedObjectIds` opcionais, ou use `client.scene3d.applyEdits()` no SDK. Para apps OAuth, isso exige o escopo `workflows:write`. O [viewport de cena 3D](https://nodaro.ai/docs/developers/embed/scene3d#edit-a-baked-scene) produz essas operações para você.

## Renderização
A prévia no navegador e a renderização em MP4 usam o mesmo leitor, então uma cena fica igual nas duas. A versão 2 aceita geometria de massinha e animação rígida; assets com textura, skinning ou morph targets são recusados.

| Limite da versão 2 | Valor |
| --- | --- |
| Entidades semânticas | 100 |
| Nós de malha | 2.000 |
| Triângulos | 200.000 |
| Tomadas | 32 |
| Assets | 64 |
| Substituições | 200 |
| Bytes de assets de reprodução | 64 MiB |

O schema também limita a temporização, as dimensões, a profundidade da hierarquia e o tamanho do manifesto. O preço de uma renderização depende do tamanho de quadro do plano; veja [Renderizar vídeo](https://nodaro.ai/docs/nodes/video/render-video).

## GLBs importados
Uma nova cena pode começar a partir de arquivos GLB que já existem em revisões armazenadas. Em `POST /v1/3d-scene/generate`, `inputAssets` seleciona até oito deles, cada um no formato `{ id, revisionId, assetId, label? }`. As `references` de imagem e de vídeo continuam em um campo separado.

- As importações exigem um mecanismo de criação com suporte a importação. O mecanismo Básico, e os mecanismos sem importação, as recusam antes de cobrar.
- Você envia só ids. O Nodaro verifica o seu acesso à revisão exata e fornece ele mesmo o hash e o tamanho em bytes. Uma URL ou um comprovante enviado por quem faz a chamada é recusado.
- Quando o mecanismo lê um GLB importado, o Nodaro verifica o acesso de novo e emite uma autorização de download de curta duração. As autorizações são credenciais de transporte: elas nunca fazem parte do plano de cena.
- Uma revisão salva pode manter cópias privadas dos arquivos a partir dos quais foi criada. Essas cópias pertencem ao dono da revisão, continuam fixadas durante as edições manuais e nunca aparecem entre os assets de reprodução nem entre os downloads públicos.

## Ler os arquivos binários pela API
Um manifesto da versão 2 nomeia os assets, mas os bytes vêm da API autenticada, com a autenticação bearer comum:

| Método | Caminho | O que retorna |
| --- | --- | --- |
| `GET` | `/v1/3d-scene/revisions/:revisionId` | O manifesto da cena e os descritores dos assets dela. |
| `GET` | `/v1/3d-scene/revisions/:revisionId/assets/:assetId` | Um asset de reprodução, como um GLB ou a trilha de câmera. |
| `GET` | `/v1/3d-scene/revisions/:revisionId/source` | O arquivo-fonte nativo editável, quando a revisão mantém um. |

- Os assets de reprodução exigem permissão para ver o workflow da revisão. O arquivo-fonte nativo exige permissão para editá-lo. As revisões pessoais só podem ser lidas pelo dono.
- Uma revisão excluída ou inacessível responde `404`, e toda resposta traz `Cache-Control: no-store`.
- No SDK, `client.scene3d.assetBytes(revisionId, asset)` e `client.scene3d.sourceBytes(revisionId)` retornam um `ArrayBuffer` e verificam o tamanho declarado.

Veja a [API de cenas 3D](https://nodaro.ai/docs/developers/api/3d-scenes) para os endpoints de geração, edição e renderização.

## Frequently asked questions

### Quais unidades e eixos uma cena 3D do Nodaro usa?

Metros, em um sistema de coordenadas destro, com o eixo Y para cima. Os quadros são numerados a partir de zero, e as rotações de Euler são em radianos.

### Qual é a diferença entre as cenas da versão 1 e da versão 2?

Uma cena da versão 1 descreve formas primitivas e quadros-chave esparsos para os objetos e a câmera, tudo dentro do plano. Uma cena da versão 2 acrescenta geometria GLB armazenada, entidades semânticas, uma trilha de câmera densa e tomadas contíguas, e os arquivos binários dela ficam atrás da API autenticada.

### Como valido um plano de cena no meu código?

Use os schemas do pacote @nodaro/shared. scene3DAnyPlanSchema aceita as duas versões, e scene3DPlanSchema valida só a versão 1.

### Editar uma cena altera o plano original?

Não. Cada edição cria uma nova revisão imutável, com o próprio id de revisão e um vínculo com a revisão pai. O plano que você editou não muda, e uma edição da versão 2 mantém os arquivos de geometria base e de câmera como estão.

### Quais arquivos GLB uma cena da versão 2 pode usar?

Geometria de massinha com animação rígida. Assets com textura, skinning ou morph targets são recusados. Uma cena comporta no máximo 100 entidades, 2.000 nós de malha, 200.000 triângulos, 32 tomadas e 64 MiB de assets de reprodução.