Formato de cena 3D

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) e de Editar cena 3D (Edit 3D Scene) retornam um plano em output_data.scenePlan. O Renderizar vídeo (Render Video) transforma um plano em MP4, e o viewport de cena 3D 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:

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.

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:

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.

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 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.

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.

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:

• 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 para os endpoints de geração, edição e renderização.