cli-anything-blender

¿Qué hace cli-anything-blender?

Una interfaz de línea de comandos con estado para edición de escenas 3D, que sigue los mismos patrones que el CLI de GIMP. Utiliza un formato de descripción de escenas JSON con generación de scripts bpy para el renderizado real en Blender.

Instalación

Este CLI se instala como parte del paquete cli-anything-blender:

pip install cli-anything-blender

Requisitos previos:

• Python 3.10+
• blender (>= 4.2) debe estar instalado en tu sistema

Uso

Comandos básicos

# Mostrar ayuda
cli-anything-blender --help

# Iniciar modo REPL interactivo
cli-anything-blender

# Crear un nuevo proyecto de escena
cli-anything-blender scene new -o scene.blend-cli.json

# Ejecutar con salida JSON (para consumo por agentes)
cli-anything-blender --json --project scene.blend-cli.json scene info

Modo REPL

Cuando se invoca sin un subcomando, el CLI entra en una sesión REPL interactiva:

cli-anything-blender
# Introduce comandos interactivamente con autocompletado y historial

Grupos de comandos

Escena (Scene)

Comandos de gestión de escenas.

Comando	Descripción
new	Crear una nueva escena
open	Abrir una escena existente
save	Guardar la escena actual
info	Mostrar información de la escena
profiles	Listar perfiles de escena disponibles
json	Imprimir el JSON de la escena

Grupo de objetos (Object Group)

Comandos de gestión de objetos 3D.

Comando	Descripción
add	Añadir un objeto primitivo 3D
remove	Eliminar un objeto por índice
duplicate	Duplicar un objeto
transform	Transformar un objeto (trasladar, rotar, escalar)
set	Establecer una propiedad del objeto (nombre, visible, ubicación, rotación, escala, padre)
list	Listar todos los objetos
get	Obtener información detallada de un objeto

Material (Material)

Comandos de gestión de materiales.

Comando	Descripción
create	Crear un nuevo material
assign	Asignar un material a un objeto
set	Establecer una propiedad del material (color, metálico, rugosidad, especular, alfa, etc.)
list	Listar todos los materiales
get	Obtener información detallada de un material

Grupo de modificadores (Modifier Group)

Comandos de gestión de modificadores.

Comando	Descripción
list-available	Listar todos los modificadores disponibles
info	Mostrar detalles de un modificador
add	Añadir un modificador a un objeto
remove	Eliminar un modificador por índice
set	Establecer un parámetro del modificador
list	Listar modificadores en un objeto

Cámara (Camera)

Comandos de gestión de cámaras.

Comando	Descripción
add	Añadir una cámara a la escena
set	Establecer una propiedad de la cámara
set-active	Establecer la cámara activa
list	Listar todas las cámaras

Luz (Light)

Comandos de gestión de luces.

Comando	Descripción
add	Añadir una luz a la escena
set	Establecer una propiedad de la luz
list	Listar todas las luces

Animación (Animation)

Comandos de animación y fotogramas clave.

Comando	Descripción
keyframe	Establecer un fotograma clave en un objeto
remove-keyframe	Eliminar un fotograma clave de un objeto
frame-range	Establecer el rango de fotogramas de la animación
fps	Establecer los FPS de la animación
list-keyframes	Listar fotogramas clave de un objeto

Grupo de renderizado (Render Group)

Comandos de configuración y salida de renderizado.

Comando	Descripción
settings	Configurar ajustes de renderizado
info	Mostrar ajustes de renderizado actuales
presets	Listar preajustes de renderizado disponibles
execute	Renderizar la escena (genera script bpy)
script	Generar script bpy sin renderizar

Vista previa (Preview)

Comandos de captura de paquete de vista previa real y sesión de vista previa en vivo.

Comando	Descripción
preview recipes	Listar recetas de vista previa disponibles
preview capture	Renderizar un paquete de vista previa real para la escena activa
preview latest	Devolver el último paquete de vista previa existente
preview live start	Iniciar una sesión de vista previa en vivo y publicar el primer paquete
preview live push	Publicar un paquete actualizado en la sesión en vivo
preview live status	Leer el estado actual de la sesión en vivo sin renderizar
preview live stop	Detener la sesión en vivo sin eliminar artefactos

Artefactos típicos del paquete para la receta quick:

• hero.png del renderizado de vista previa real de Eevee
• workbench.png del renderizado real de Blender Workbench

Las sesiones en vivo persisten:

• session.json como cabeza mutable
• directorios de paquetes inmutables
• trajectory.json como historial de comandos-a-vista previa de solo adición

Lado del visor:

• cli-hub previews inspect <bundle-or-session>
• cli-hub previews html <bundle-or-session> -o page.html
• cli-hub previews watch <session-dir> --open
• cli-hub previews open <bundle-or-session>

Sesión (Session)

Comandos de gestión de sesión.

Comando	Descripción
status	Mostrar estado de la sesión
undo	Deshacer la última operación
redo	Rehacer la última operación deshecha
history	Mostrar historial de deshacer

Ejemplos

Crear un nuevo proyecto

Crear un archivo de proyecto de escena Blender.

cli-anything-blender scene new -o myscene.blend-cli.json
# O con salida JSON para uso programático
cli-anything-blender --json scene new -o myscene.blend-cli.json

Sesión REPL interactiva

Iniciar una sesión interactiva con soporte de deshacer/rehacer.

cli-anything-blender
# Introduce comandos interactivamente
# Usa 'help' para ver los comandos disponibles
# Usa 'undo' y 'redo' para navegar por el historial

Gestión de estado

El CLI mantiene el estado de la sesión con:

• Deshacer/Rehacer: Hasta 50 niveles de historial
• Persistencia del proyecto: Guardar/cargar el estado del proyecto como JSON
• Seguimiento de sesión: Rastrear modificaciones y cambios

Formatos de salida

Todos los comandos soportan modos de salida duales:

• Legible para humanos (por defecto): Tablas, colores, texto formateado
• Legible para máquinas (bandera --json): JSON estructurado para consumo por agentes

# Salida humana
cli-anything-blender --project scene.blend-cli.json scene info

# Salida JSON para agentes
cli-anything-blender --json --project scene.blend-cli.json scene info

Flujo de trabajo de vista previa

Usa las vistas previas de Blender cuando el agente necesite puntos de control visuales fiables:

# Listar recetas de vista previa
cli-anything-blender --project scene.blend-cli.json preview recipes

# Capturar un paquete de vista previa real
cli-anything-blender --json --project scene.blend-cli.json preview capture --recipe quick

# Iniciar un bucle de vista previa en vivo
cli-anything-blender --json --project scene.blend-cli.json preview live start --recipe quick --mode poll --source-poll-ms 500

# Consultar la cabeza actual en vivo sin renderizar
cli-anything-blender --json --project scene.blend-cli.json preview live status --recipe quick

Para agentes, preview capture --json devuelve metadatos del paquete más rutas de archivos de artefactos. preview live status --json devuelve metadatos de la sesión más un trajectory_summary compacto.

Para agentes de IA

Al usar este CLI de forma programática:

1. Usa siempre la bandera --json para obtener salida analizable
2. Verifica los códigos de retorno - 0 para éxito, distinto de cero para errores
3. Analiza stderr para mensajes de error en caso de fallo
4. OBLIGATORIO: Usa rutas absolutas para todas las operaciones de archivos (renderizado, archivos de proyecto). Las rutas relativas son propensas a fallos en ejecución en segundo plano.
5. Usa preview capture o preview live ... para verificación visual en lugar de inferir la calidad de la escena solo a partir del JSON
6. Lee las rutas de artefactos devueltas como hero.png y workbench.png; la carga útil JSON referencia archivos, no incluye bytes de imagen
7. Trata _bundle_dir como una sola instantánea; para un historial en vivo estable, usa _session_dir más _trajectory_path
8. Usa cli-hub previews ... solo para inspeccionar/abrir vistas previas existentes; la generación de vistas previas siempre ocurre a través de cli-anything-blender preview ...

Más información

• Documentación completa: Consulta README.md en el paquete
• Cobertura de pruebas: Consulta TEST.md en el paquete
• Metodología: Consulta HARNESS.md en cli-anything-plugin

Versión

1.0.0