OpenKatana · 3D starter:
OpenKatanaScene creates an editable local 3D scene from a built-in template and renders it using WebGL, the browser-based technology used to display 3D graphics. It offers a scene-based alternative to generative image or video creation: the visual content comes from a constructed 3D scene rather than a generation model, and the node does not require generation credits. Because the scene remains editable, you can continue refining it through OpenKatana’s Studio/AI tools instead of treating the rendered result as a fixed image. This makes the node useful for establishing a reusable 3D starting point, testing visual ideas, and preparing short animated scenes with a controlled image size and timeline.
OpenKatana · 3D starter Input Parameters:
project_id
A required STRING identifying the OpenKatana project for the scene operation. The default is my-film; no length limits or naming rules are specified in the provided interface. This value is passed to OpenKatana’s scene tool so the operation can be associated with the intended project. Use a clear, consistent identifier to keep your work organized, especially when switching between several projects. The supplied code does not establish what happens when you reuse an existing identifier, so do not assume that changing or retaining this value automatically creates a separate version or protects earlier work.
template
A required selection choosing the built-in starting template for your scene. The available options are exactly product, morph, and physics. The node does not explicitly declare a default; product is the first listed option. Your choice determines which template is requested from the scene tool and therefore which starting scene you will work with. The provided source does not show these templates’ contents, so their exact objects, materials, movements, and camera setups cannot be confirmed from this interface. Preview the available choices before committing to a longer render rather than relying on their names alone to predict the result.
width
A required INT setting the requested render width in pixels. The default is 640, the minimum is 64, the maximum is 3840, and the interface increment is 2. Together with height, this controls the image dimensions and aspect ratio. Increasing the width provides more horizontal pixels but also increases the amount of image data the renderer must process. For example, a width of 640 paired with a height of 360 produces a 16:9 image. Start with a smaller width when evaluating a template, then raise it when you are ready for a more detailed render.
height
A required INT setting the requested render height in pixels. The default is 360, the minimum is 64, the maximum is 2160, and the interface increment is 2. This works with width to determine whether the render is landscape, portrait, or square. A taller image contains more vertical pixels and can increase rendering work; changing the width-to-height ratio also changes the available image shape, so check the composition after switching formats. For example, 640 by 640 requests a square image, while 360 by 640 requests a portrait image.
frames
A required INT setting the requested number of animation frames. The default is 60, the minimum is 1, and the maximum is 1800. A frame is one image in the animation sequence, so this setting directly affects how many images must be rendered. The nominal sequence duration in seconds is frames / fps: the defaults request 60 frames at 30 frames per second, equivalent to two seconds of playback. Use a small frame count for quick checks and a larger count for longer sequences. The supplied code does not show how each template adjusts its animation when you change the frame count.
fps
A required INT setting the requested animation frame rate in frames per second. The default is 30, the minimum is 1, and the maximum is 120. This establishes how many frames correspond to one second of animation. At a fixed frame count, increasing the frame rate shortens the nominal playback duration: 60 frames correspond to two seconds at 30 fps but one second at 60 fps. To increase the frame rate while keeping the same duration, increase frames proportionally. Higher frame rates allow more closely spaced motion samples, but they do not guarantee better-looking motion because the result also depends on the template’s animation.
OpenKatana · 3D starter Output Parameters:
result_json
A STRING containing the scene tool’s response, exposed as a JSON-formatted result through the node’s response wrapper. This is the node’s only output socket; it does not directly return a ComfyUI image tensor, frame batch, or video socket. Use it to inspect the information returned by the scene operation and, where supported by your workflow, pass that information to tools that understand the response. The supplied code does not include the response wrapper’s implementation or a response example, so exact JSON fields, file locations, success indicators, and error structures cannot be documented reliably. Inspect the actual returned value rather than assuming it contains a particular path or key.
OpenKatana · 3D starter Usage Tips:
- Begin with the default
640by360resolution and a short sequence to evaluate the selected template before requesting a larger render. Lower pixel counts and fewer frames reduce the amount of rendering work. - Calculate your intended duration before rendering using
frames = duration in seconds × fps. For example, five seconds at 30 fps requires150frames, while five seconds at 60 fps requires300frames. - Choose an aspect ratio that matches your intended presentation: use
640by360for a landscape test,360by640for portrait, or640by640for square. Review the framing after changing the dimensions. - Compare
product,morph, andphysicswith modest render settings before choosing your starting point. Their detailed contents are not shown in the supplied code, so a preview is more reliable than assumptions about their names. - Keep
project_idconsistent when working with the intended project, and check existing project contents before rerunning an operation. The provided interface does not document overwrite or versioning behavior. - Inspect
result_jsonafter execution. If you need rendered images or video in another part of your ComfyUI workflow, first determine what the actual response provides; this node does not expose those media types directly. - When making later scene edits through Studio/AI, keep advanced settings compatible: transparent output requires post effects to be disabled, and a camera path requires a perspective camera without conflicting camera animation tracks. These are scene-editing constraints, not additional inputs on this node.
OpenKatana · 3D starter Common Errors and Solutions:
Input outside the supported range
- Explanation: This is a descriptive issue rather than a quoted backend message. The interface defines limits for image dimensions, frame count, and frame rate. Values outside those limits may fail input validation or be rejected before the scene operation runs; the exact error text is not provided.
- Solution: Keep
widthbetween 64 and 3840,heightbetween 64 and 2160,framesbetween 1 and 1800, andfpsbetween 1 and 120. Use the dimension controls’ increment of 2. If troubleshooting, return to the defaults first.
Unsupported template selection
- Explanation: This is a descriptive issue rather than a quoted backend message. The node accepts only
product,morph, orphysics. A workflow edited externally or submitted programmatically may contain a different value. - Solution: Select one of the three available options in the node. When preparing workflow data outside the interface, preserve the exact spelling and lowercase form.
3D module failed to load: ...
- Explanation: The renderer raises an error beginning with this text when its browser page does not expose the expected OpenKatana3D module after loading. The full message includes collected errors and blocked requests, which can help identify why the rendering application did not initialize.
- Solution: Inspect the complete message for the specific loading error or blocked request. Confirm that the OpenKatana installation and its rendering application files are available, then retry a template without custom edits. If the failure persists, provide the full message when requesting support rather than only the opening sentence.
Undeclared scene dependency: ...
- Explanation: The renderer blocks a requested project file when it is not included among the scene’s declared dependencies. This can occur when an edited scene references an asset that the renderer has not been authorized to load. The message includes the relative path of the requested file.
- Solution: Check the reported asset reference and ensure the file is included in the project and properly declared through the supported scene-authoring process. Correct broken references rather than trying to bypass the renderer’s dependency checks.
Transparent output currently requires post effects disabled
- Explanation: Scene validation rejects transparent output when any post-effect value is enabled. The provided validation checks post settings including bloom, focus, aperture, and maximum blur. This concerns the underlying scene configuration, not the six input controls on this node.
- Solution: In your scene-editing tools, either disable transparency or disable the post effects. If you need a transparent background, remove or set the relevant post-effect values to zero before rendering again.
camera_path currently requires a perspective camera
- Explanation: An edited scene contains a camera path while its camera is configured as orthographic. The supplied validator does not support that combination.
- Solution: Switch the scene camera to perspective if you want to retain the camera path, or remove the camera path if an orthographic view is essential to your composition.
camera_path owns the camera; remove conflicting camera tracks
- Explanation: The scene defines a camera path and also includes animation tracks targeting the camera. Validation rejects this because both mechanisms would control the same camera.
- Solution: Choose one camera animation method. Keep the camera path and remove conflicting camera-targeted tracks, or remove the camera path and retain the track-based animation.
Invalid advanced scene effect or motion-blur values
- Explanation: This is a descriptive issue rather than a quoted error string. The supplied validator limits bloom to 0–5, focus to 0–10000, aperture and maximum blur to 0–0.1, motion-blur samples to an integer from 1–32, and shutter to 0–1. Invalid values in an edited scene can prevent rendering even when the node’s visible inputs are valid.
- Solution: Review these settings in the scene-authoring tools and restore values within the supported ranges. For troubleshooting, reduce motion-blur samples to 1 and disable post effects, then reintroduce the desired effects gradually.
