OpenKatana · Click points:
OpenKatanaPoints prepares point-based guidance for image segmentation, helping you indicate which areas should belong to a selected subject and which areas should be excluded. It converts positions expressed on a relative 0–1 scale into whole-pixel locations matched to the image dimensions, so you can describe a location independently of a particular resolution. This is useful in subject cut-out workflows, where a segmentation model uses a few carefully chosen locations to distinguish the subject from its surroundings. The node validates the point format and coordinate range before converting the locations, helping catch incorrectly entered guidance early. It is a coordinate-conversion utility rather than a segmentation model: it does not detect objects, generate masks, or track subjects by itself.
OpenKatana · Click points Input Parameters:
image
A required IMAGE connection that supplies the frame dimensions used for coordinate conversion. The node expects ComfyUI’s image-batch layout: batch size, height, width, and channels. It reads the height and width without examining the image content or modifying the image. Each horizontal coordinate is multiplied by the image width minus one, and each vertical coordinate is multiplied by the image height minus one; the results are rounded to whole pixels. Consequently, the same relative point produces different pixel coordinates at different resolutions while retaining its relative position within the frame. For a batch, the node produces one set of coordinate strings based on the batch dimensions, not separate results for each frame. There is no default image, selectable option, or explicit minimum or maximum image size defined by this node.
positive
A required STRING containing a JSON list of positive guidance points, with the default value [[0.5, 0.5]]. Each point must be a two-element list written as [x, y], where x specifies the horizontal position and y specifies the vertical position. The minimum coordinate value is 0 and the maximum is 1, both inclusive: [0, 0] corresponds to the top-left pixel, [1, 1] corresponds to the bottom-right pixel, and [0.5, 0.5] is approximately the center. At least one positive point is required, and the node defines no maximum point count. In a compatible point-prompted segmentation workflow, these points indicate areas you want included in the subject. For example, [[0.4, 0.3], [0.5, 0.6]] provides two inclusion hints. The node checks the JSON structure and coordinate range, then converts every point to pixel coordinates while preserving its order; whether the points successfully identify your subject depends on their placement and the downstream segmenter.
negative
A required STRING containing a JSON list of negative guidance points, with the default value []. Although the input itself is required, its list may be empty, allowing you to proceed without exclusion hints. Each supplied point must use the same [x, y] structure and normalized coordinate range as positive points: minimum 0 and maximum 1, inclusive. The minimum point count is zero, and no maximum point count is defined. In a compatible segmentation workflow, negative points identify areas you want excluded, such as background regions or a nearby object being incorrectly included. For example, [[0.1, 0.8]] supplies one exclusion hint near the lower-left area of the frame. The node validates and converts these points independently of the positive list; it does not require matching point counts or pair points between the two lists.
OpenKatana · Click points Output Parameters:
positive_coordinates
A STRING containing a JSON list of positive points converted into whole-pixel coordinates. Each entry is an object with x and y fields, rather than the two-element lists used when entering points. The conversion is ``round(x * (width
- 1))
horizontally andround(y * (height - 1))vertically, placing valid coordinates between 0 and the corresponding image dimension minus one. For example, with a 1920 × 1080 image, the default positive point[[0.5, 0.5]]produces[{"x": 960, "y": 540}]``. Point order is preserved. This output supplies the inclusion locations expected by compatible downstream point-prompted segmenters; it is serialized text, not an image, mask, or detected subject.
negative_coordinates
A STRING containing a JSON list of negative points converted into whole-pixel coordinates, using the same image dimensions, rounding method, and x/y object structure as positive_coordinates. An empty negative list produces the string []. When points are present, their order is preserved, and their pixel positions tell a compatible downstream segmenter where you want exclusion guidance applied. This output does not remove anything from an image by itself; it provides locations for the segmentation stage to interpret. In the supplied cut-out workflow, this output is connected to the segmenter’s negative-coordinate input only when negative points have been supplied.
OpenKatana · Click points Usage Tips:
- Connect the same image batch that your downstream segmenter uses. If you calculate coordinates from one resolution and apply them to another, the pixel positions may no longer align with the intended subject.
- Enter points as valid JSON, such as
[[0.35, 0.4], [0.6, 0.55]]. Use square brackets, numeric values, and commas between entries; do not use parentheses, comments, or trailing commas. - Place positive points clearly inside the subject rather than directly on an uncertain boundary. The default
[[0.5, 0.5]]is useful only when the center of the frame falls on the subject you want selected. - Start with a few well-placed positive points and leave negative as
[]. If your segmenter includes unwanted regions, add negative points inside those regions and check the resulting mask. - Convert a known pixel location into normalized coordinates using
x / (width - 1)andy / (height - 1)for dimensions greater than one pixel. This reverses the node’s scaling and helps you transfer locations measured in an image editor. - Remember that 0 and 1 are allowed, so you can address the outermost pixels. This node does not enforce the strictly interior coordinates or paired-point requirements used by the separate image-morphing functionality.
- In the supplied SAM2 video cut-out workflow, choose points on the clip’s first frame: the segmenter receives them with frame_index set to 0 and propagates the selection through the video. OpenKatanaPoints itself does not track points or generate separate prompts for later frames.
- Connect positive_coordinates and negative_coordinates to matching coordinate-string inputs, such as those on Sam2VideoSegmentationAddPoints in the supplied workflow. These outputs are not substitutes for mask or image connections.
OpenKatana · Click points Common Errors and Solutions:
positive: expected a JSON list of [x, y] points
- Explanation: The positive text could not be read as JSON. Common causes include a missing bracket, a trailing comma, or using parentheses instead of square brackets.
- Solution: Enter a valid JSON list such as
[[0.5, 0.5]]. For multiple points, use[[0.4, 0.3], [0.6, 0.7]].
negative: expected a JSON list of [x, y] points
- Explanation: The negative text could not be read as JSON. Even when you do not need exclusion points, any nonempty text must follow JSON syntax.
- Solution: Use
[]for no negative points, or enter a valid list such as[[0.1, 0.8]]. Remove comments, trailing commas, and other non-JSON text.
positive: expected at least one [x, y] point
- Explanation: The positive value is either an empty list or a JSON value that is not a list. Blank text is also treated as an empty list, which is not allowed for positive guidance.
- Solution: Supply at least one point inside an outer list, such as
[[0.5, 0.5]]. Do not use[],null, or a JSON object in place of the point list.
negative: expected a list
- Explanation: The negative text is valid JSON, but its top-level value is not a list. For example,
nullor a single coordinate object does not meet the required structure. - Solution: Use
[]when you do not need negative points, or wrap each coordinate pair in an outer list, such as[[0.2, 0.7]].
positive: each point is [x, y] with both values in 0..1, got ...
- Explanation: A positive point has the wrong structure or contains an invalid coordinate. The actual message replaces the dots with the offending value. Causes include entering pixel coordinates such as
[320, 240], using quoted numbers, supplying more or fewer than two coordinates, or entering[0.5, 0.5]without an outer list. - Solution: Format every point as a two-number list inside the main list, such as
[[0.5, 0.5]]. Keep both coordinates between 0 and 1, inclusive, and normalize any pixel positions before entering them.
negative: each point is [x, y] with both values in 0..1, got ...
- Explanation: A negative point does not contain exactly two numeric coordinates within the accepted range. The actual message includes the invalid point, helping you locate the problem.
- Solution: Correct the indicated entry to a normalized pair such as
[0.2, 0.8]inside the outer list. If you do not need exclusion guidance, replace the entire negative value with[].
ValueError: not enough values to unpack (expected 4, got ...)
- Explanation: The connected image has fewer than the four dimensions expected for a ComfyUI image batch. For example, an image without a batch dimension cannot be unpacked into batch size, height, width, and channels. The exact reported dimension count depends on the supplied data.
- Solution: Connect a standard ComfyUI IMAGE output, rather than raw coordinates, a mask, or an incorrectly shaped custom tensor. If a custom node creates the image, make sure it outputs the standard batch-height-width-channels layout.
ValueError: too many values to unpack (expected 4)
- Explanation: The connected image data has more than four dimensions, so the node cannot extract the expected image-batch dimensions.
- Solution: Use an IMAGE output with exactly four dimensions in batch-height-width-channels order. If a custom video or image-processing node adds extra dimensions, convert its output to a standard ComfyUI image batch before connecting it.
