MiniMax H3 Mask Grid Preview & Snap:
MiniMaxH3MaskGridPreview helps you see how an intended edit area fits MiniMax H3’s 32×32-pixel cell grid before you generate. It converts the requested area into complete cells, then displays the selected cells over the canvas so you can spot areas that may be included or excluded. You can compare the cell boundaries with the original mask edge, choose how cells are selected, and expand or contract the selection by whole cells. This makes it easier to check the edit area visually and use the resulting cell-aligned mask in an H3 workflow.
MiniMax H3 Mask Grid Preview & Snap Input Parameters:
image
The ComfyUI IMAGE canvas used as the background for the preview and as the source of its frame count, height, and width. Connect the exact resized H3 canvas frames that you intend to VAE-encode so the displayed cells correspond to the canvas used for generation. The image must have a frame dimension and at least three color channels; its width and height must be divisible by 32 for the grid to align as intended. If the image has more than three channels, the preview uses only the first three. No default, minimum, or maximum image dimensions are specified in this node’s interface.
mask
The ComfyUI MASK that identifies where you want generation, such as a mask from SAM3 Detect, SAM3 Track to Mask, or painting. White represents the requested generation area. The node uses this mask to determine which cells to select and, when enabled, to draw the original boundary for comparison. No default or numeric range is specified. The provided source does not show the internal mask-preparation rules, so use a mask that corresponds to the connected canvas and frames.
cell_selection
Chooses how the requested area becomes a selection of complete cells. The tooltip identifies Runtime exact as the mode that reproduces H3’s latent resize and per-row maximum decision; other modes use direct pixel coverage and may select cells more or less conservatively. The available choices come from GRID_MODES, whose contents are not included in the provided source, so no complete option list or default can be stated reliably. Choose from the options shown by the node in your installation.
cell_adjust
Expands or shrinks the selected area in complete 32×32-pixel H3 cells after cell selection. Positive values grow the selection, negative values shrink it, and 0 leaves it unadjusted. This can help you include a little more surrounding area or avoid editing neighboring content, but each step is a whole-cell adjustment rather than a pixel-level change. Minimum: -8; maximum: 8; default: 0; step: 1.
overlay_opacity
Controls how strongly the orange selected-cell overlay appears on the preview. At 0.0, the overlay does not visibly tint the canvas; at 1.0, selected areas display the orange overlay at full strength, making the underlying image harder to see there. This changes the preview’s appearance, not the selected cells. Minimum: 0.0; maximum: 1.0; default: 0.38; step: 0.01.
show_grid
Controls whether cyan lines mark every 32×32-pixel cell boundary in the preview, including the canvas’s bottom and right edges. Turn it on to inspect how the selection follows the grid, or off for a less cluttered image. This display setting does not change the selected mask. Options: True or False; default: True.
show_source_outline
Controls whether the boundary of the original input mask appears in white on the preview. Keep it on to compare the area you requested with the complete cells selected for H3, or turn it off when you only need to inspect the cell overlay. This display setting does not change the selected mask. Options: True or False; default: True.
MiniMax H3 Mask Grid Preview & Snap Output Parameters:
snapped_mask
A ComfyUI MASK representing the selected area after it has been snapped to complete H3 cells and adjusted by cell_adjust. Use this cell-aligned mask with H3 Set Generation Mask when you want the generation mask to match the selection shown by this node. It is the selection itself, not a visualization containing grid lines or colors.
grid_preview
A ComfyUI IMAGE showing the canvas with selected cells tinted orange. Depending on the display settings, it also shows cyan cell boundaries and the original mask boundary in white. Use it to judge whether the selected cells cover the area you intended before continuing. The overlay, grid, and outline are visual aids; use snapped_mask when a downstream node needs the mask.
grid_info
A STRING summary of the grid and selection. It reports the grid’s width and height in cells, the 32×32-pixel cell size, selected-cell counts, the total number of cells per frame, the chosen mode, and the cell adjustment. For up to eight frames, it lists each frame’s selected-cell count; for more than eight, it reports the minimum, maximum, and sum across frames. Use it to check whether the selection is unexpectedly empty, unusually large, or different between frames.
MiniMax H3 Mask Grid Preview & Snap Usage Tips:
- Connect the same resized canvas frames that you will send through the H3 workflow. Check that both canvas dimensions are divisible by 32 before relying on the visual alignment.
- Start with
cell_adjustset to0and bothshow_gridandshow_source_outlineenabled. Compare the white original boundary with the orange selected cells to see what the cell selection adds or excludes. - Choose
Runtime exactwhen you need the mode described by the node as reproducing H3’s runtime cell decision. Try the other choices shown in your installation when you want to compare more or less conservative selections; their exact names and rules are not available in the provided source. - If the selected area needs a margin, increase
cell_adjustgradually. If it reaches content you want to preserve, try a negative value and inspect the preview again. Each step affects complete cells. - Lower
overlay_opacitywhen you need to see image detail beneath the selection; raise it when the selected cells are hard to distinguish. This setting does not altersnapped_mask. - Check
grid_infofor each-frame counts when working with a short sequence. A count of0means no cells were selected for that frame; the preview can help you investigate why.
MiniMax H3 Mask Grid Preview & Snap Common Errors and Solutions:
Expected ComfyUI IMAGE [frames,H,W,C], got [...]
- Explanation: This error comes directly from the node when
imagedoes not have four dimensions or has fewer than three color channels. For example, a standalone height-by-width image without a frame dimension does not meet the expected shape. - Solution: Connect a standard ComfyUI
IMAGEcontaining frames, height, width, and at least three color channels. Check any upstream conversion node if the image was assembled manually.
Canvas width or height is not divisible by 32
- Explanation: The image input’s tooltip says both dimensions must be divisible by 32 so the displayed cells align with H3. The provided
previewmethod does not itself show a dedicated error message for this condition; any validation inside the mask-quantization helper is not provided. - Solution: Resize or prepare the canvas to dimensions divisible by 32, then feed that same resized canvas into this node and the H3 workflow.
Mask and image dimensions or frame counts do not match
- Explanation: A mask prepared for a different canvas or sequence may be rejected or may not represent the area you expect. The supplied source passes the image’s frame count and dimensions to a helper, but does not show that helper’s matching or resizing behavior, so a specific error string cannot be confirmed.
- Solution: Prepare the mask for the canvas and frames connected to
image. Check the preview andgrid_infoafter reconnecting it.
No cells appear selected
- Explanation:
grid_infomay report0selected cells when the requested area does not result in a selected cell under the chosen settings. A negativecell_adjustcan also shrink a selection. The exact thresholds of the unavailable selection modes cannot be determined from the supplied source. - Solution: Confirm that the input mask marks the intended area in white, set
cell_adjustto0, and inspect the white source outline. Then compare the availablecell_selectionmodes or increasecell_adjustif you need a larger selection.
The preview selection differs from the original mask edge
- Explanation: This is often expected: the node selects complete 32×32-pixel cells, while the original mask may have an irregular or fine boundary. The white outline shows the original boundary; the orange overlay shows the cell-aligned selection.
- Solution: Use the grid and outline to inspect the difference. Adjust the selection mode or
cell_adjustto obtain the coverage you need, and passsnapped_maskonward when you want the mask shown by the cell selection.
The image looks too orange or the grid obscures details
- Explanation: A high
overlay_opacitymakes selected areas harder to inspect, and cyan grid lines can add visual clutter. These are preview settings, not mask-selection errors. - Solution: Lower
overlay_opacityor turnshow_gridoff temporarily. Keepshow_source_outlineon if you still need to compare the original boundary.
