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 cujoparentRevisionIdé a revisão de origem. Cada MP4 renderizado usa uma revisão exata. - Versões. Leia
schemaVersionantes 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/capabilitiesinforma 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.
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
nodeNameopcional 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
spacedela diz em qual referencial os valores são lidos:localsignifica 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.worldsignifica 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 2 | Valor |
|---|---|
| Entidades semânticas | 100 |
| Nós de malha | 2.000 |
| Triângulos | 200.000 |
| Tomadas | 32 |
| Recursos | 64 |
| Substituições | 200 |
| Bytes de recursos 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.
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étodo | Caminho | O que retorna |
|---|---|---|
GET | /v1/3d-scene/revisions/:revisionId | O manifesto da cena e os descritores dos recursos dela. |
GET | /v1/3d-scene/revisions/:revisionId/assets/:assetId | Um recurso 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 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 trazCache-Control: no-store. - No SDK,
client.scene3d.assetBytes(revisionId, asset)eclient.scene3d.sourceBytes(revisionId)retornam umArrayBuffere 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.
Páginas relacionadas
Incorporar o viewport de cena 3D
Gerar cena 3D
Editar cena 3D
Cenas 3D
Última atualização
Incorporar o viewport de cena 3D
Incorpore o viewport de cena 3D do Nodaro em um iframe e controle-o com postMessage: troca inicial, mensagens de estado, eventos de edição, recursos e limites.
Carteiras externas
Conecte uma implantação dedicada do Nodaro Cloud à sua carteira compartilhada, que reserva, liquida e informa os créditos de cada cliente em seus produtos.