OpenKatana · Review mask:
OpenKatana_review_mask helps you inspect a clip’s masks before relying on them for cutout or compositing work. A mask, also called a matte, defines which parts of an image remain visible and which become transparent. The review process samples frames across the clip, includes the final frame, and supports a review-sheet workflow so you can look for problems without examining every frame individually. It can flag separate mask regions, which may indicate unwanted isolated patches or an inconsistent cutout, although separate regions can also be intentional. Reviews are associated with a content fingerprint of the clip’s mask files, allowing OpenKatana’s strict review checks to distinguish reviewed masks from changed or unreviewed ones. This is an inspection step rather than a repair operation: it helps you decide whether a matte is ready or needs refinement.
OpenKatana · Review mask Input Parameters:
project_id
A required STRING that identifies the OpenKatana project for the tool call. The node passes this value into its argument-preparation process so the operation can be associated with the intended project. Use the identifier for the project containing the clip and masks you want to inspect; an incorrect identifier may prevent the tool from resolving the intended project or its resources. The supplied interface does not specify a default, an allowed identifier format, a list of options, or minimum and maximum lengths.
arguments
A required STRING containing the arguments passed to the review tool. The node processes this text through OpenKatana’s argument-preparation utilities before invoking the operation. This is the place for the tool-specific request rather than additional node sockets, but the supplied code does not show the accepted argument schema, required keys, or parsing rules. The underlying review routine works with a timeline, a clip selection, an output location, and review-layout settings; these details do not establish the exact field names accepted by this STRING. Follow the review_mask tool’s argument specification in your installation rather than copying the internal routine’s signature as an assumed request format. No default value, length limits, or enumerated options are specified in the supplied node interface.
after
An optional STRING with a default of None in the execution method. Although the node accepts this value, the supplied method does not reference it when preparing arguments or invoking the tool, so this code does not establish any effect on sampling, review findings, or approval. Do not assume it selects a frame or changes the review operation. If your surrounding workflow uses this socket to connect operations, follow that workflow’s conventions; no particular string format, minimum, maximum, or selectable options are documented here.
OpenKatana · Review mask Output Parameters:
result_json
A STRING containing the response returned by the OpenKatana tool call after it has been processed by the node’s response wrapper. This is a text response, not a directly connectable image or mask output. The supplied tests confirm that the underlying review routine returns information including frames, the sampled frame indices; flags, review findings; and mask_sha256, a fingerprint calculated from the clip’s mask files. For example, a tested 12-frame clip at 30 frames per second, reviewed at 0.1-second intervals, produces frame indices [0, 3, 6, 9, 11]. The fingerprint identifies the mask content to which a review decision applies, rather than rating its quality. The supplied source does not show the response wrapper or the review_mask tool implementation, so the exact JSON envelope, any additional fields, and any review-sheet file paths cannot be specified reliably.
OpenKatana · Review mask Usage Tips:
- Review masks after generation and again after refinement. The fingerprint covers all mask frames in the clip, so changing mask content can make an earlier review decision no longer applicable.
- Use the standard 0.25-second sampling interval for the review workflow described by OpenKatana’s strict matte gate. The underlying routine defaults to this interval and four review-sheet columns; these are backend defaults, not separately exposed node inputs.
- For fast movement or suspected flicker, use a shorter sampling interval if your installed tool’s argument schema supports it. The tests demonstrate 0.1-second sampling, but a sampled review still does not replace checking every frame when frame-level accuracy matters.
- Always inspect the final sampled frame. The tested behavior includes the clip’s last frame even when it does not fall on the regular sampling interval, helping you catch problems near the end of the shot.
- Treat a
separate regionsflag as a reason to inspect the matte, not as proof that it is wrong. Detached objects can be intentional; unwanted islands or regions that appear and disappear may need correction. - If the review reveals unwanted islands or holes, use the available mask-refinement workflow before reviewing again. The provided tests demonstrate hole filling and keeping the largest region, but keeping only the largest region may remove legitimate separate subjects.
- Keep visual inspection and acceptance distinct. The strict gate checks an accepted review record associated with the current mask fingerprint; the supplied node code does not show that running this node automatically records acceptance.
OpenKatana · Review mask Common Errors and Solutions:
review the matte of clip A with review_mask (every 0.25 s and the last frame)
- Explanation: This is a strict-gate message indicating that no review record was found for the current mask fingerprint of clip A. Other clips will appear with their own identifiers.
- Solution: Review the indicated clip using the prescribed sampling workflow, inspect the results, and ensure that your project’s review process records the acceptance decision for the current masks.
the matte of clip A was rejected in review: refine it (analyze_clip masks mode refine) or re-run masks
- Explanation: The strict gate found a review record for the clip’s current mask content, but that record marks the matte as rejected.
- Solution: Refine the matte through the indicated workflow or regenerate the masks, then inspect the updated result and record a new decision. Simply repeating a review without addressing the problem does not guarantee acceptance.
unexpected inputs: ...
- Explanation: The node explicitly raises this TypeError when execution receives additional fields that are not declared by its typed interface. The message lists the unexpected field names. This check concerns extra execution fields, not necessarily keys inside the
argumentstext. - Solution: Use only the exposed inputs:
project_id,arguments, and optionalafter. Place tool-specific settings inargumentsaccording to the installed tool’s documented schema rather than adding unsupported node inputs.
Invalid or unsupported arguments
- Explanation: This is a possible failure category, not an exact error string shown in the supplied code. The node prepares and processes the argument text before calling the tool, so an unsupported request structure or missing tool-required information may prevent execution.
- Solution: Check the argument specification for review_mask in your installed OpenKatana version. Verify the required fields and value types, and do not assume the internal review routine’s parameter names are the public argument schema.
Project, clip, or mask files cannot be resolved
- Explanation: This is a possible resource-related failure category; the exact error wording is not supplied. Reviewing masks depends on locating the intended project and clip, while fingerprinting requires access to the clip’s numbered mask files. The provided implementation reads names such as
00000.pngfrom the configured mask directory. - Solution: Confirm that
project_ididentifies the correct project, that the requested clip exists, and that its mask directory contains the expected frame sequence. Check file permissions and ensure the declared frame count agrees with the available files.
separate regions
- Explanation: This text is confirmed as part of a review flag, not an execution error. It indicates that the review detected separate mask regions, which can represent unwanted islands or legitimate detached parts of the scene.
- Solution: Inspect the affected samples before changing the matte. If the regions are unwanted, refine or regenerate the masks; if they are intentional, preserve them and evaluate the matte according to your shot’s requirements.
