OpenKatana · Inspect identity:
OpenKatana_inspect_identity helps you visually check whether generated material stays consistent with references bound to your OpenKatana project, such as a person, character, or product. It creates a side-by-side comparison sheet using the largest detected face in each reference and each selected candidate frame; when no face is detected, it uses a central crop instead and labels that limitation. This makes it easier to spot changes in appearance and document your acceptance or rejection of the material. The comparison is visual only: detecting a face does not establish a biometric identity match, and the tool does not provide an identity similarity score. In strict review mode, generated material identified through OpenKatana’s Comfy-origin tracking must be accepted against every bound identity reference before the timeline can pass the identity review requirement. Reviews are tied to the reference definitions, so changing a reference can require a new review.
OpenKatana · Inspect identity Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which you want to inspect an asset. The project provides the asset records, bound references, and review context used for the comparison, so choose the project containing both your candidate material and its references. This is a project identifier, not the candidate asset identifier or an image file path. The supplied node interface does not specify a default value, allowed identifier format, minimum length, maximum length, or list of options.
arguments
A required STRING containing the tool-call arguments as JSON text. The underlying inspection API requires an asset_id string identifying the candidate asset and supports references as a list of reference-name strings or null, frames as a list of integer frame indices or null, accept as true, false, or null, and note as a text string. These are properties inside arguments, not separate node inputs. The API defaults are null for references, frames, and accept, and an empty string for note; the supplied code does not show how omitted references or frames are selected automatically. Explicit reference names and frame indices therefore make your intended comparison clearer. For example, {"asset_id":"g1","references":["lead"],"frames":[0],"accept":null,"note":"Initial visual inspection"} requests a comparison using a named reference and the candidate’s first frame, without specifying acceptance or rejection. Frame 0 is the first frame, and each reference asset is inspected at frame 0 regardless of the candidate frames you request. No default for the arguments input itself, numeric frame limits, or maximum argument length is shown in the node interface.
after
An optional STRING accepted by the shared node interface. In the supplied execution method, this value is accepted but is not read or forwarded to the inspection tool, so no effect on reference selection, frame selection, visual comparison, or review decisions is demonstrated. The method’s default is None when this input is omitted; no string default, allowed options, or length limits are shown. Do not rely on this value to record acceptance or modify an inspection, because those controls belong in arguments.
OpenKatana · Inspect identity Output Parameters:
result_json
A STRING containing the serialized response returned through the OpenKatana tool wrapper. The supplied comparison implementation returns a sheet path pointing to the generated identity.jpg, a detections list describing the compared reference and candidate frames, and a meaning message stating that the result is “visual comparison only; a detected face is not a biometric identity match.” Each detection includes the asset identifier, frame index, face-detection information, and crop information; reference entries also include the reference name. The sheet places labeled reference crops before the selected candidate-frame crops, allowing you to compare their appearance directly. A label containing (no face: centre) means that a central crop was used because no face was detected, not that the candidate failed an identity test. The complete outer response structure and any additional review-related fields are not shown in the supplied wrapper code, so inspect the returned JSON rather than assuming these comparison fields always appear at its top level. This output is a text response, not a ComfyUI IMAGE output.
OpenKatana · Inspect identity Usage Tips:
- Bind your intended references before inspecting generated material, and use their names in the
referencesproperty ofarguments. Reference names identify bound reference records, whileasset_ididentifies the candidate asset. - Choose candidate frames explicitly when you need a repeatable review. Start with a small selection showing clear facial detail, then include frames with different angles, expressions, or lighting to check consistency throughout a clip.
- Put a clear, representative image at the start of each reference asset. The comparison implementation always uses frame 0 from each reference, even when you inspect later frames of the candidate.
- Inspect the comparison sheet before recording a decision. Use
acceptset to null for an initial inspection, then submit true or false to express your acceptance or rejection, with a helpfulnoteexplaining your judgment. - Check the labels and crop content carefully. The tool selects the largest detected face, which may be a background person rather than your intended subject; a central fallback crop may also miss the most important details of a product or character.
- Keep each comparison focused. Every reference asset and requested candidate frame adds a 240-pixel-wide tile to a single horizontal sheet, so large selections produce increasingly wide images that can be harder to review.
- In strict review mode, review generated material against every bound identity reference. Reinspect it after changing a reference definition, because the supplied tests demonstrate that a changed reference digest invalidates the previous approval for that reference configuration.
OpenKatana · Inspect identity Common Errors and Solutions:
reference [name]: asset [id] is no longer in the project
- Explanation: This error is explicitly raised when a bound reference points to an asset identifier that cannot be found in the project’s asset list. The reference record still exists, but one of the assets it needs is missing.
- Solution: Restore the missing asset or update the bound reference to use an asset currently available in the project, then run the inspection again.
inspect generated clip G against identity reference lead with inspect_identity
- Explanation: This review-gate message appears in the supplied tests when generated clip G has not received the required accepted review against the bound reference named lead. It is a review requirement, not a face-detection failure.
- Solution: Inspect the generated asset against that reference, open the comparison sheet, and record
acceptas true only if you judge the material acceptable. Repeat the process for any other required identity references.
Review gate reports rejected
- Explanation: The supplied tests confirm that a rejected review leaves the identity gate unsatisfied and produces a message containing
rejected; the complete message is not shown. Creating a comparison sheet alone does not override a recorded rejection. - Solution: Review why the material was rejected, improve or replace it if necessary, and perform another inspection. Record a new acceptance only after the material meets your requirements.
unexpected inputs: [input names]
- Explanation: The node explicitly raises this TypeError if it receives extra fields outside its declared inputs. Tool-specific settings such as
asset_idandframesare not exposed as separate inputs in this node interface. - Solution: Use only
project_id,arguments, and the optionalafterinput. Put the candidate asset, reference names, frame selection, and review settings inside the JSON text inarguments.
Invalid JSON or missing tool arguments
- Explanation: This is a troubleshooting category rather than a verified exact error string. The wrapper processes
argumentsbefore invoking the tool, and the inspection API requires anasset_id. Malformed JSON or an omitted required argument can prevent the call from reaching the comparison stage. - Solution: Use a valid JSON object with double-quoted property names and strings, include
asset_id, and use JSON values such astrue,false, andnullrather than Python spellings. Check for trailing commas and unmatched brackets.
Missing frame image or invalid frame selection
- Explanation: The exact error message is not shown, but the implementation must load each reference’s frame 0 and every requested candidate frame. Missing media files or a frame index outside the available material can therefore prevent the sheet from being created.
- Solution: Confirm that the project’s media files are available and that each requested frame exists. For a single-frame asset, use
framesset to[0]; for a clip, select indices within its actual frame count.
Output directory already exists or cannot be written
- Explanation: The exact surfaced message is not shown, but the comparison code creates its output directory with
exist_ok=Falseand then savesidentity.jpginside it. An existing destination or insufficient filesystem permissions can stop this process. - Solution: Check the destination reported by OpenKatana, ensure the application can write there, and resolve any output-folder collision through the project’s normal output-management process. Avoid deleting project media or review records when clearing temporary outputs.
(no face: centre)
- Explanation: This is a comparison-sheet label, not an execution error. It means no face was detected in that tile and the tool used a central crop instead; the sheet may still be useful for a visual review.
- Solution: If you need to compare faces, choose a clearer candidate frame or a reference whose first frame shows the face prominently. If you are reviewing a non-face subject, inspect the fallback crop manually and do not interpret it as an automatic identity verdict.
