Cut (Qwen-Image 2.1) — BlueBox:
CutQwenImage21 prepares images for Qwen-Image 2.1 workflows by adapting them to a calculated target size, helping you standardize reference images before further processing. Available as “Cut (Qwen-Image 2.1) — BlueBox” in the BlueBox/Qwen category, it combines automatic or manually controlled resolution selection with three approaches to fitting an image: center cropping, padding, or stretching. These approaches let you prioritize a filled frame, preservation of the complete composition, or exact frame coverage without borders. The sizing process also checks whether the selected dimensions remain unchanged when passed through its internal size-verification logic and, where possible, substitutes a stable alternative with an aspect ratio close to the original image. This helps make image preparation more consistent, although it does not guarantee that every later node will leave the image unchanged. This node prepares images only; it does not generate images, encode prompts, or perform AI-based detail enhancement.
Cut (Qwen-Image 2.1) — BlueBox Input Parameters:
image
A required IMAGE containing the picture or image batch you want to prepare. The node reads the original width and height to select a target size, then applies the selected fitting method to the image data. Its main processing method expects ComfyUI’s standard four-dimensional image layout: batch, height, width, and channels. For a batch, all images share the same dimensions and are processed to the same target size. Connect a standard image-producing node, such as an image loader, rather than a latent, mask, or filename. There is no default image, and the interface does not specify minimum or maximum image dimensions.
resolution_mode
A required selection with the options default and manual; the default is default. This controls how the working resolution is chosen before the target width and height are calculated. With default, the node chooses a resolution automatically from the original image dimensions, so resolution_value does not determine the result. With manual, the node uses resolution_value after passing it through its manual-resolution adjustment logic. Automatic selection is convenient when you want the node to choose for you, while manual selection gives you more direct control over the resolution setting. The supplied source does not show the automatic-selection thresholds or the exact manual-adjustment rules.
resolution_value
A required INT used when resolution_mode is manual. Its default is 1024, and the interface step is 32. The minimum and maximum are defined by MIN_RESOLUTION and MAX_RESOLUTION, respectively; their numerical values are not included in the supplied source, so exact limits cannot be stated here. The node adjusts this value through its manual-resolution logic before using it to calculate target dimensions. Treat it as a working resolution setting rather than an instruction to make both sides exactly that many pixels: the actual width and height are selected separately, taking the original image shape into account. In default mode, this field remains part of the interface but is not used to choose the resolution.
mode
A required selection with the options crop, pad, and stretch; the default is crop. This determines how the image is fitted to the calculated target dimensions. crop uses a center-crop operation, which can remove content near the edges when the original and target shapes differ; the detailed crop implementation is not included in the supplied source. pad scales the complete image proportionally to fit inside the target canvas, centers it, and fills any remaining space with the fixed value 0.0, which appears black for ordinary RGB images. stretch resizes directly to the target width and height without preserving the original proportions, so shapes may appear wider or narrower. Both the shown padding and stretching implementations use bilinear interpolation, a standard resizing method that blends neighboring pixels.
Cut (Qwen-Image 2.1) — BlueBox Output Parameters:
image
An IMAGE containing the processed picture or batch after cropping, padding, or stretching. Its spatial dimensions match the returned width and height, making it suitable for connecting to subsequent image-processing or reference-image inputs. The selected mode determines whether this image may have lost edge content, gained black borders, or changed proportions. The shown padding and stretching implementations preserve the batch and channel structure while changing the spatial size. This output is an image, not an encoded latent or conditioning object.
width
An INT giving the final image width in pixels. This is the selected target width after the node’s size-selection and stability-checking steps, not necessarily the original width or the value entered in resolution_value. You can use it to inspect the actual size or drive a compatible downstream width input. Together with height, it describes the exact rectangular dimensions of the processed image.
height
An INT giving the final image height in pixels. Like width, it reflects the target dimensions selected by the node rather than simply repeating the original image height or the requested resolution setting. Use it alongside width when checking image proportions or coordinating dimensions with later workflow stages. The output image has this many pixels along its vertical axis.
resolution
An INT containing the effective working resolution used to calculate the target dimensions. In default mode, this comes from automatic resolution selection; in manual mode, it comes from adjustment of resolution_value. It is separate from the actual output width and height and should not be interpreted as a guarantee of a square image. It can also be connected to a compatible resolution input, such as the one on Text Encode Qwen Image 2.1, to coordinate resolution settings across the workflow; downstream nodes still apply their own resizing rules.
Cut (Qwen-Image 2.1) — BlueBox Usage Tips:
- Start with
resolution_modeset todefaultwhen you want automatic sizing. Inspect the returnedwidth,height, andresolutionbefore deciding whether you need manual control. - Use
manualwhen you need to control the working resolution explicitly. Start with the default value of 1024, then adjust within the limits offered by your installed interface; changingresolution_valuehas no effect whileresolution_modeisdefault. - Choose
cropwhen filling the frame is more important than retaining every edge detail. Keep important subjects near the center, and preview images containing faces, lettering, or objects close to the borders. - Choose
padwhen preserving the complete composition matters, such as for product references or artwork with important edge details. Expect black borders wherever the scaled image does not fill the target canvas; this node does not expose a padding-color control. - Choose
stretchonly when proportion changes are acceptable. It avoids both padding and cropping, but can visibly distort faces, circles, lettering, and other recognizable shapes. - Connect
imageto your next image-processing or reference-image node, and usewidthandheightwherever you need the actual pixel dimensions. Do not substituteresolutionfor both dimensions unless the receiving node specifically expects a resolution setting. - When using Text Encode Qwen Image 2.1, you can connect the returned
resolutionto its resolution input. Its documented value of 0 instead keeps each reference at its own size with rounding to multiples of 32, so that is an alternative when you want to minimize additional resolution-based resizing; verify the resulting dimensions in your workflow. - Preview the processed image before encoding or generation, especially with extreme portrait or landscape compositions. This lets you catch unwanted cropping, large borders, or stretched proportions early.
Cut (Qwen-Image 2.1) — BlueBox Common Errors and Solutions:
ValueError: not enough values to unpack (expected 4, got 3)
- Explanation: The node’s main method expects a four-dimensional image tensor, including a batch dimension. A three-dimensional image from a custom node can trigger this Python error when the node reads its shape; the exact message depends on the supplied data.
- Solution: Connect a standard ComfyUI IMAGE output. If a custom processing node removed the batch dimension, correct that node or restore the standard batch-height-width-channels layout before connecting it here.
ValueError: too many values to unpack (expected 4)
- Explanation: This can occur when the supplied image data has more than four dimensions, such as a custom video or nested-batch representation. The node does not include logic to interpret additional dimensions.
- Solution: Convert the data to a standard ComfyUI image batch using an appropriate conversion node. If you are processing video, supply frames in the normal IMAGE batch format rather than a video-specific tensor.
AttributeError: 'NoneType' object has no attribute 'shape'
- Explanation: This possible Python error means the image input reached the node without valid image data. The node immediately reads the image shape and does not include an explicit check for an empty value.
- Solution: Confirm that the image input is connected and that the upstream node successfully produced an image. Check that the selected file exists and can be loaded, then run the workflow again.
CUDA out of memory
- Explanation: Resizing can require memory for both the source image and the result. Padding also allocates a target-sized canvas, so large images, large batches, or high target resolutions can exhaust available GPU memory. This is a possible PyTorch runtime error, not a custom message defined by this node.
- Solution: Try a lower manual resolution, process fewer images at once, or reduce the source dimensions before this node. Free memory held by other running workflows or applications if necessary.
Required input is missing
- Explanation: ComfyUI may report a validation error if a required input is absent; the full message may name the missing input. All four inputs are required, even though
resolution_valuedoes not affect resolution selection indefaultmode. - Solution: Connect a valid IMAGE and ensure that
resolution_mode,resolution_value, andmodehave valid settings. If a workflow was imported from another version, recreate the node and reconnect it.
Value not in list
- Explanation: A saved workflow or API request may contain an unsupported selection. The accepted values are exactly
defaultormanualforresolution_mode, andcrop,pad, orstretchformode. This is a possible ComfyUI validation message rather than an exception explicitly raised in the node. - Solution: Select an available dropdown option or correct the API request to use the exact supported string. Avoid substituting labels such as
autoorresize.
The resolution setting appears to do nothing
- Explanation: This is a behavior issue rather than a runtime error. In
defaultmode, the node selects resolution from the source dimensions and does not useresolution_value. Manual settings are also adjusted internally, so a requested value is not necessarily the effective value. - Solution: Switch
resolution_modetomanualand inspect the returnedresolution,width, andheight. Use these outputs to confirm what the node actually selected.
The result has missing edges, black borders, or distorted proportions
- Explanation: These are expected consequences of the fitting modes rather than error messages: center cropping can remove edges, padding can add black space, and stretching can alter proportions.
- Solution: Use
padto retain the complete image without changing its proportions,cropto prioritize a filled frame, orstretchwhen distortion is acceptable. Preview the output and choose the trade-off that best suits your artwork.
