ImageScaleToTotalPixels:
ImageScaleTotalPixels resizes an image in two stages: it first applies a size multiplier, then, when enabled, adjusts the result toward a target total pixel count while preserving its aspect ratio. You can use it for a quick enlargement or reduction, for preparing images at a consistent approximate resolution, or for combining both steps. When you provide a mask, the node applies the same resizing settings to it. It can also prepare encoded versions for a latent-based workflow when a VAE is available. Dimensions may be rounded to a chosen multiple, so the final pixel count can differ slightly from the target.
ImageScaleToTotalPixels Input Parameters:
pixels
The required IMAGE to resize. Its starting width, height, and aspect ratio determine the result of both scaling stages. Connect the image you want to process; this input has no numeric minimum, maximum, or default specified in the source.
upscale_method
The required interpolation method used whenever resizing occurs. This setting affects how new pixels are calculated and therefore how the resized image and any connected mask look. The default is lanczos. The interface obtains its choices from UPSCALE_METHODS, but the provided source does not list those choices, so no other options can be confirmed here. It has no numeric range.
scale_by
A required size multiplier applied before the megapixel stage. 1.0 leaves dimensions unchanged at this stage and skips its resizing and dimension rounding; 1.5 aims for 50% larger width and height, while 0.5 aims for half the width and height. The default is 1.0, the minimum is 0.01, the maximum is 8.0, and the control step is 0.01. If the megapixel stage is enabled, it can resize the image again, so the final dimensions will not necessarily reflect this multiplier alone.
megapixels
The required target for the second scaling stage, expressed in units of 1,048,576 pixels. For example, a target of 1.0 is approximately 1024 × 1024 pixels for a square image; other aspect ratios produce different width and height combinations. This setting takes effect only when enable_megapixels is True. The default is 1.0, the minimum is 0.01, the maximum is 64.0, and the control step is 0.01. Dimension rounding can make the actual total differ from the target.
multiple
The required multiple to which scaled width and height are rounded during either active scaling stage. This helps produce dimensions suited to workflows that expect regular size increments. The default is 8, the minimum is 8, the maximum is 128, and the control step is 4. Choosing a larger multiple can move the final dimensions further from an exact size or megapixel target. It does not round an unchanged image when scale_by is 1.0 and enable_megapixels is False.
enable_megapixels
A required switch controlling the second scaling stage. When True, the node resizes the result of scale_by toward the megapixels target; when False, it keeps the result of the first stage without applying a megapixel constraint. The default is True. Its options are True and False; it has no numeric range.
mask
An optional MASK to resize alongside the image using the same scaling settings. Connect a mask when you need a corresponding resized mask for later work. If you leave it disconnected, the node supplies a zero-filled mask at the output image’s size instead. This input has no default value or numeric range specified.
vae
An optional VAE used to encode the resized image into a latent representation. When a mask is connected, the node also converts the resized mask into an image-like form and encodes it with the same VAE. If you leave this input disconnected, both latent outputs are zero-filled placeholders rather than encoded content. This input has no default value or numeric range specified.
ImageScaleToTotalPixels Output Parameters:
image
The resulting IMAGE after the enabled scaling stages. It retains the input’s aspect ratio as the resizing target, subject to dimension rounding. Use this output when you need the resized picture itself. With scale_by set to 1.0 and enable_megapixels set to False, the scaling pipeline returns the original image unchanged.
latent_image
A LATENT containing the VAE-encoded resized image when vae is connected. This is the image result prepared for a latent-based workflow, rather than a directly viewable picture. Without a VAE, it is a zero-filled latent sized from the output image, not an encoding of the image.
mask
The resized MASK when one is connected. It follows the same scaling settings as the image, allowing you to carry a corresponding mask forward. Without an input mask, this output is zero-filled at the output image’s height and width; a zero result in that case does not mean a mask was detected in the image.
latent_mask
A LATENT containing a VAE encoding of the resized mask when both mask and vae are connected. To encode it, the node repeats the mask values across three image channels before passing them to the VAE. It is therefore an encoded representation of the mask, not the ordinary MASK output. If either optional input is absent, this output is a zero-filled latent placeholder.
ImageScaleToTotalPixels Usage Tips:
- To keep the image unchanged by this node’s scaling pipeline, set
scale_byto1.0andenable_megapixelstoFalse. To use only the size multiplier, leave the megapixel stage disabled. - For a consistent approximate output pixel count across images of different sizes, enable
enable_megapixelsand setmegapixelsto your target. Expect dimensions to vary with each image’s aspect ratio and themultiplesetting. - Start with the default
multipleof8when preparing dimensions for a VAE workflow. If you need dimensions rounded to a larger increment, increase it, then check whether the resulting size still suits your task. - Connect both
maskandvaeonly when you need their corresponding outputs. A missing mask produces a zero mask, and a missing VAE produces zero latent outputs; those placeholders do not contain the missing input’s content. - Check the visual result when resizing a mask. The selected
upscale_methodis applied to the mask as well as the image, so the appearance of mask edges can change.
ImageScaleToTotalPixels Common Errors and Solutions:
Missing required input: pixels
- Explanation: The node needs an image to determine what to resize. This is a possible workflow validation message; its exact wording depends on the host.
- Solution: Connect an
IMAGEtopixelsand run the workflow again.
Invalid value for scale_by, megapixels, or multiple
- Explanation: A value outside the declared control range may be rejected by the host. The permitted ranges are
0.01–8.0forscale_by,0.01–64.0formegapixels, and8–128formultiple. - Solution: Return the value to its permitted range. For
multiple, use a value available in the control’s increments of4.
Invalid upscale_method selection
- Explanation: The node expects one of the choices supplied by
UPSCALE_METHODS. The provided source does not list the complete set, so a manually entered or outdated choice may fail validation. - Solution: Select a method from the node’s current dropdown.
lanczosis the documented default.
Unexpected final image dimensions
- Explanation: When
enable_megapixelsisTrue, the node resizes again after applyingscale_by. Active scaling stages also round dimensions according tomultiple, so the final size may not equal a simple multiplication or the exact megapixel target. - Solution: Disable
enable_megapixelsif you want only multiplier-based scaling. For a closer megapixel target, start with the defaultmultipleof8and inspect the resulting dimensions.
Mask and image dimensions do not match
- Explanation: The same scaling settings are applied to both inputs, but the code does not establish that an independently supplied mask already matches the image. If their starting dimensions differ, their results may still differ.
- Solution: Supply a mask that matches the input image’s width and height before connecting them to this node.
Latent output appears empty or contains only zeros
- Explanation: Without a connected
vae,latent_imageandlatent_maskare deliberately zero-filled.latent_maskis also zero-filled when nomaskis connected, even if a VAE is present. - Solution: Connect a VAE to obtain
latent_imagecontent. Connect both a mask and a VAE to obtain an encodedlatent_mask.
Out-of-memory error during resizing or VAE encoding
- Explanation: Large source images, a high
scale_byvalue, or a highmegapixelstarget can require substantial memory. Connecting a VAE adds encoding work. - Solution: Reduce
scale_byormegapixels, process a smaller image, or leave the VAE disconnected when you only need the image and mask outputs.
