OpenKatana · Analyze camera motion:
OpenKatana_analyze_camera_motion helps you inspect animated camera movement for sudden changes that may deserve attention before you finalize a shot. It analyzes evaluated camera samples, which represent the camera’s actual position and viewing direction after animation and constraints have been applied, rather than judging movement only from keyframes. The analysis measures travel speed, changes in aiming direction, and changes in angular speed, and estimates the pixel distance associated with camera rotation during the shutter interval. These measurements help you investigate abrupt aim changes, distinguish continuous movement from planned cuts, and assess potential rotational streaking. This is a measurement and quality-checking tool, not an automatic correction tool or an artistic verdict: it does not establish whether a move looks good, and its rotational shutter estimate is not a complete simulation of motion blur in the rendered image.
OpenKatana · Analyze camera motion Input Parameters:
project_id
A required STRING identifying the OpenKatana project associated with this analysis. The underlying API resolves the project, accesses its state, and directs camera-analysis reports to a project-specific camera-reports output location. Use the identifier of an existing, accessible project so your analysis is associated with the intended workspace. This value identifies the project; it does not itself supply the camera animation. The provided node interface does not specify a default value, minimum or maximum string length, or a list of allowed identifiers.
arguments
A required STRING carrying the arguments passed to the camera-motion analysis tool. Supply a JSON object containing the camera-analysis document and, when needed, the underlying tool settings jolt_threshold and jolt_ratio; these are entries inside this string, not separate node inputs. The API declares defaults of 2500 for jolt_threshold and 3 for jolt_ratio, but the supplied implementation does not show the flagging logic or accepted ranges, so their exact effects and valid limits cannot be fully documented here. The document must contain evaluated camera_samples in the structure expected by OpenKatana’s Blender helpers, together with the metadata needed to interpret them. Each inspected camera row permits the fields f, pos, fwd, pos_open, fwd_open, pos_close, fwd_close, lens, and hfov_deg; the shown checks require consecutive master-frame numbers, three-coordinate lists for pos, fwd, fwd_open, and fwd_close, and a numeric hfov_deg between 0.1 and 179. Because the complete document schema is not included in the context, use the document produced by the appropriate Blender helper rather than constructing an assumed schema. The node interface specifies no default string, minimum or maximum length, or enumerated options for arguments.
after
An optional STRING accepted by the node’s execution method. In the supplied implementation, after is accepted but is not read or forwarded into the camera-analysis arguments, so it has no demonstrated effect on the calculated measurements or report contents. It may serve a surrounding workflow convention, but that behavior is not established by the provided code. You can leave it unconnected when you do not need such a convention. The execution method defaults to None when this input is omitted; no default text value, length limits, or allowed string options are specified.
OpenKatana · Analyze camera motion Output Parameters:
result_json
A STRING containing the tool response serialized by the node’s response wrapper. The underlying camera-analysis API returns a dictionary, and this output is the node’s single channel for exposing that response to your workflow. The supplied analysis code constructs per-frame measurements including frame, cut, speed, aim_deg_s, pan_px, shutter_rotation_px, and aim_accel. Travel speed is the distance between successive camera positions multiplied by the frame rate, expressed in scene-coordinate units per second; aim speed is the change in forward direction in degrees per second; pan_px estimates the pixel displacement associated with that directional change using image width and horizontal field of view; and aim_accel measures the change in angular speed per second. The shutter rotation estimate compares the viewing directions at shutter opening and closing. Frame-to-frame measurements remain unset where a previous comparison is unavailable or where a frame is marked as a cut, and acceleration also requires a preceding valid aim-speed measurement. The complete returned dictionary and response envelope are not shown, so inspect the actual JSON before building downstream field lookups rather than assuming a particular nesting structure or report-path key.
OpenKatana · Analyze camera motion Usage Tips:
-
Use evaluated camera samples from OpenKatana’s Blender helpers. This preserves the movement produced by constraints and other evaluated animation behavior, which may differ from what raw keyframes suggest.
-
Keep the document’s frame rate and image width consistent with the shot you are analyzing. Frame rate affects the calculated speeds and acceleration, while image width and horizontal field of view affect the pixel-based rotation estimates.
-
Preserve consecutive master-frame numbers. If you want to examine only part of an animation, generate a properly sampled segment rather than removing arbitrary rows from an existing sample list.
-
Make sure planned cuts are represented correctly in the analysis document. The shown calculation skips frame-to-frame motion comparisons at marked cuts, helping prevent an intentional camera change from being interpreted as continuous movement.
-
Begin with the underlying tool defaults of
jolt_threshold2500 andjolt_ratio3. If you change these settings insidearguments, compare reports from the same shot and inspect the relevant frames; the provided code does not establish the exact flagging rule, so do not treat either setting as a guaranteed visual-quality boundary. -
Read
speedin the context of your scene scale. The code measures distance in scene-coordinate units, so you should not assume the values are meters per second unless your scene uses that scale. -
Treat
shutter_rotation_pxas a rotational streak estimate, not a complete blur measurement. It uses the change in camera forward direction and does not fully describe roll, depth-dependent effects from camera translation, or movement of objects within the scene. -
Review flagged moments visually before revising animation. An intentional whip pan or abrupt stylized move can produce strong measurements without being a mistake, and this node does not automatically adjust the camera or video.
OpenKatana · Analyze camera motion Common Errors and Solutions:
Camera samples must contain consecutive master frames
- Explanation: A sample’s
fvalue does not match the expected master-frame sequence. Missing frames, duplicate frame numbers, or samples in the wrong order can cause this exact error. - Solution: Regenerate the evaluated samples for a continuous frame range. Confirm that every sample advances by exactly one master frame and that the document’s starting frame matches the first sample.
pos needs three coordinates
- Explanation: A camera position is missing or is not represented as a list containing exactly three coordinates.
- Solution: Supply
posas a three-number list representing the evaluated camera position. Prefer regenerating the document through the Blender helper so its structure remains consistent.
fwd needs three coordinates
- Explanation: The evaluated camera viewing direction is missing or is not a list of exactly three coordinates.
- Solution: Check that each sample contains a valid three-number
fwdlist. Do not substitute a descriptive direction, a two-dimensional point, or Euler rotation values for the expected forward vector.
fwd_open needs three coordinates
- Explanation: The camera viewing direction at shutter opening is missing or does not contain exactly three coordinates. The analysis needs this direction to estimate rotation during exposure.
- Solution: Regenerate camera samples that include shutter-opening evaluation, and confirm that
fwd_openis a three-number list for every sample.
fwd_close needs three coordinates
- Explanation: The camera viewing direction at shutter closing is missing or does not contain exactly three coordinates.
- Solution: Regenerate the samples with shutter-closing evaluation included, and confirm that each
fwd_closevalue is a three-number list.
Invalid numeric coordinate value
- Explanation: This is a descriptive error category rather than a confirmed literal message. The code validates every coordinate in
pos,fwd,fwd_open, andfwd_closeas a number, so text, missing values, or other unsupported values can fail validation. - Solution: Check that these lists contain actual JSON numbers rather than quoted numbers or empty entries. If the data was exported incorrectly, regenerate it instead of replacing invalid values with arbitrary coordinates.
Invalid hfov_deg value
- Explanation: This is a descriptive error category; the exact validation message is not shown. Each sample’s horizontal field of view is checked as a number in the range 0.1 to 179 degrees, and it is used to convert angular movement into an estimated pixel distance.
- Solution: Supply the evaluated horizontal field of view in degrees within the accepted range. Check that your export has not supplied radians, a focal length, or a zero value in place of
hfov_deg.
Unsupported camera-row field
- Explanation: This is a descriptive error category. The code applies a field-validation helper to each camera row with the listed camera-sample fields, but the helper’s exact error text is not provided.
- Solution: Use the camera-row structure generated by the Blender helper and avoid adding custom metadata directly to sample rows unless the document contract supports it.
Invalid arguments JSON or missing document
- Explanation: This is a descriptive error category, not a confirmed literal message. The node passes
argumentsthrough argument-processing helpers, and the underlying tool requires adocument; malformed JSON or an absent document can prevent analysis from starting. - Solution: Use a valid JSON object with double-quoted property names and no trailing commas. Include the complete camera-analysis document rather than only a video path or a standalone list of positions.
Project or report-location access failure
- Explanation: This is a descriptive error category. The API resolves the project, accesses its state, and obtains a
camera-reportsoutput location before running the analysis; the exact failure messages are not shown. - Solution: Confirm that
project_ididentifies an available project and that the OpenKatana process can access its files and write to its output location.
unexpected inputs: ...
- Explanation: The node explicitly raises this error when execution receives keyword inputs outside its recognized typed fields. Tool arguments such as
jolt_thresholdmust not be introduced as additional sockets for the interface shown here. - Solution: Use only
project_id,arguments, and the optionalafterinput. Place the camera document and supported analysis settings inside theargumentsJSON string.
