NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
Incorporações

Formato de cena 3D

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

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. As tarefas de Gerar cena 3D e de Editar cena 3D retornam um plano em output_data.scenePlan. O Renderizar vídeo 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:

ExportaçãoO que é
Scene3DPlanV1, Scene3DPlanV2O tipo de cada versão.
Scene3DPlanA união das duas versões.
scene3DAnyPlanSchemaUm validador que aceita as duas versões.
scene3DPlanSchemaUm validador só para a versão 1.
scene3DPlanV2SchemaUm 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.
LimiteValor
Objetos por cena100
Quadros-chave por objeto ou por trilha de câmera240
Tamanho do id de um objeto64 caracteres
Largura e altura do quadro100 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çãoCampos
set-objectobjectId e changes em qualquer campo do objeto, exceto o id
add-objectobject
remove-objectobjectId
set-camerachanges
set-lightingchanges
set-backgroundcolor

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

Recursos

Uma referência de recurso 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 recurso 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 recursos, 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 recurso, 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 uma tarefa 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; recursos com textura, skinning ou morph targets são recusados.

Limite da versão 2Valor
Entidades semânticas100
Nós de malha2.000
Triângulos200.000
Tomadas32
Recursos64
Substituições200
Bytes de recursos de reprodução64 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.

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 recursos de reprodução nem entre os downloads públicos.

Ler os arquivos binários pela API

Um manifesto da versão 2 nomeia os recursos, mas os bytes vêm da API autenticada, com a autenticação bearer comum:

MétodoCaminhoO que retorna
GET/v1/3d-scene/revisions/:revisionIdO manifesto da cena e os descritores dos recursos dela.
GET/v1/3d-scene/revisions/:revisionId/assets/:assetIdUm recurso de reprodução, como um GLB ou a trilha de câmera.
GET/v1/3d-scene/revisions/:revisionId/sourceO arquivo-fonte nativo editável, quando a revisão mantém um.
  • Os recursos 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.

Perguntas frequentes

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. Recursos 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 recursos de reprodução.

Última atualização

Nesta página