姿势图库 · 单图:
PoseGalleryImage, displayed in ComfyUI as “姿势图库 · 单图,” loads one reference image from the plugin’s built-in pose gallery or a configured custom gallery. It helps you find and prepare a pose reference without repeatedly locating image files by hand, making it useful for figure drawing, composition planning, and pose-guided image generation. It can preserve the reference’s original dimensions, resize it with white padding, crop it to fill a chosen format, stretch it, or mirror it horizontally. During loading, it also corrects orientation using the image’s EXIF information and places transparent areas against a white background. This is an image-loading and preparation node, not a pose detector or an image-generation model, and it requires no inference models or downloads for its own operation. To use a reference to guide a generated character’s pose, you should follow it with DWPose or OpenPose preprocessing and a compatible ControlNet.
姿势图库 · 单图 Input Parameters:
pose_id
A required STRING identifying the single image to retrieve from the selected gallery. The intended way to set this is to click “打开姿势图库” and select an image, rather than manually entering an identifier. The node looks up this identifier in the active gallery, so it must refer to an existing image in that source; it is not a filename, file path, or text description of a pose. Choosing a different identifier changes the reference image and its accompanying catalogue information. The default is the plugin’s DEFAULT_ID constant; its literal value is not shown in the supplied source. No minimum length, maximum length, or fixed list of identifiers is specified in the provided interface.
asset_source
A required COMBO selection determining which gallery supplies the image. The context confirms support for plugin-bundled assets and a custom gallery, with the custom directory configured through the gallery’s asset settings. This choice determines where the node looks up pose_id, so you should select the source containing your chosen reference. The available options are supplied by SOURCES, and the default is SOURCES[0], which the tooltip identifies as the plugin’s bundled assets. The supplied excerpts do not reveal the complete list of displayed option labels, so their exact spelling cannot be listed reliably. There is no numerical minimum or maximum.
resize_mode
A required COMBO selection controlling how the reference image is fitted to the intended dimensions. The exact options are “原始尺寸,” “等比留边,” “居中裁剪,” and “拉伸,” with “原始尺寸” as this node’s default. “原始尺寸” preserves the loaded image’s dimensions rather than resizing it to width and height. “等比留边” preserves the image’s proportions and adds white padding where necessary to reach the requested dimensions, helping you retain the full reference without distorting the body. “居中裁剪” preserves proportions but fills the requested dimensions by cropping around the center, which can remove content near the edges. “拉伸” resizes directly to the requested dimensions without preserving proportions, so the body may appear wider or taller than in the original. The three resizing modes use LANCZOS resampling for image resizing.
width
A required INT specifying the target width in pixels when you choose “等比留边,” “居中裁剪,” or “拉伸.” Its default is 768, its minimum is 64, its maximum is 4096, and the interface adjustment step is 8. Increasing this value produces a wider image in those modes and increases the amount of image data processed downstream; it does not create additional detail in the source reference. With “原始尺寸,” this setting does not determine the actual image width. However, the loading code still validates that the supplied width is within the allowed range, even when original dimensions are preserved.
height
A required INT specifying the target height in pixels when you choose “等比留边,” “居中裁剪,” or “拉伸.” Its default is 1024, its minimum is 64, its maximum is 4096, and the interface adjustment step is 8. Together with width, it establishes the target image format, such as a portrait-oriented 768 × 1024 reference. A larger height produces more pixels for downstream processing but cannot recover detail missing from the original image. With “原始尺寸,” the loaded image retains its own height instead; nevertheless, the supplied height must still pass the 64–4096 range validation.
flip_horizontal
A required BOOLEAN controlling whether the loaded reference is mirrored from left to right. The default is False, displayed as “不翻转”; enabling it selects True, displayed as “翻转.” Mirroring happens before any resizing or cropping, allowing you to reverse a pose’s visual direction without selecting another gallery image. This can help a reference fit your intended composition, but it also reverses visible asymmetries, text, and accessories. It changes the image only: the returned catalogue identifier and pose description still refer to the original selected record. There is no numerical minimum or maximum.
姿势图库 · 单图 Output Parameters:
图片
An IMAGE containing the selected reference after orientation correction, white-background compositing, optional horizontal mirroring, and any requested resizing. It is a standard ComfyUI image tensor containing one image, arranged as batch, height, width, and color channels, with three RGB channels and floating-point values normalized to the range 0–1. Transparent areas are merged onto white rather than preserved as transparency, and no separate transparency mask is returned. You can connect this output to an image preview or another compatible image-processing node. For pose-guided generation, send it through a suitable DWPose or OpenPose preprocessor before using the resulting pose information with a compatible ControlNet.
图片ID
A STRING containing the selected catalogue record’s id value. This identifies which reference was loaded and is useful when you want to record, reuse, or check your selection. It identifies the source gallery image rather than the processed image’s dimensions or appearance, so resizing and horizontal mirroring do not change it. Treat it as a gallery identifier, not as a filesystem path or an image-generation prompt.
姿势说明
A STRING describing the selected reference using catalogue metadata in this exact order: 姿势名称|体系|分类|角度|id. In English, these fields correspond to pose name, system, category, viewing angle, and image identifier, separated by the full-width vertical bar “|.” This gives you a readable reference label for understanding and tracking your selection. The text comes directly from the catalogue rather than from an analysis of the image, so mirroring, cropping, or resizing does not rewrite it to describe the transformed result.
姿势图库 · 单图 Usage Tips:
- Choose your reference through “打开姿势图库” whenever possible. This avoids typing mistakes in
pose_idand helps you select an image from the correct asset source. - For a full-body reference, start with
resize_modeset to “等比留边.” It preserves body proportions and keeps the complete image visible, adding white padding instead of cutting off hands, feet, or other edge details. - Use “原始尺寸” when you want to avoid resampling the reference. Changing
widthandheightwill not resize the image in this mode, although both settings must remain within their valid ranges. - Use “居中裁剪” when filling the target frame matters more than keeping every part of the reference. Preview the result before pose preprocessing, especially if the original places the head, hands, or feet close to an edge.
- Avoid “拉伸” when accurate body proportions are important. If the source and target have different proportions, stretching can change the apparent length or width of the figure.
- For a portrait reference, 768 × 1024 is the provided target-size default. Select a resizing mode other than “原始尺寸” to apply those dimensions, and avoid unnecessarily large sizes when your downstream workflow does not need them.
- Enable
flip_horizontalto test the opposite pose direction, then inspect asymmetrical details. The image is mirrored, but its catalogue description and identifier remain unchanged. - For pose control, connect
图片to DWPose or OpenPose preprocessing and then use a matching ControlNet workflow. This node alone does not extract a skeleton or enforce a pose during generation. - Configure your custom gallery directory in the gallery’s asset settings before selecting the custom source. A custom gallery needs a valid catalogue and its referenced image files, not just a folder of unlisted pictures.
姿势图库 · 单图 Common Errors and Solutions:
未知图片尺寸处理方式。
- Explanation: The supplied resize mode is not one of the four supported values. This can happen if a workflow or external call supplies an unsupported or altered option.
- Solution: Select “原始尺寸,” “等比留边,” “居中裁剪,” or “拉伸” from the node’s dropdown. If an imported workflow contains an invalid value, reset that selection.
输出宽高须在 64 至 4096 之间。
- Explanation: The supplied width or height is outside the supported range of 64–4096 pixels. Both values are validated even when “原始尺寸” is selected.
- Solution: Set both dimensions within the supported range, such as width 768 and height 1024. Use the interface’s step of 8 when adjusting them.
图片无法读取或已损坏:<filename>
- Explanation: The image loader could not open or process the referenced file. The code uses this message for image-reading errors, invalid image data, and Pillow’s decompression-bomb error, which can occur with exceptionally large images.
- Solution: Try opening the named file in an image editor. If it is unreadable, restore or replace it; if it opens, try exporting a fresh PNG or JPEG. For an exceptionally large image, reduce its dimensions before placing it in the gallery.
data/pose-zh.json 须为非空的图片记录数组。
- Explanation: The custom gallery catalogue is not a nonempty JSON array of image records. An empty catalogue or an incorrectly structured top-level value cannot provide a usable image selection.
- Solution: Check that
data/pose-zh.jsoncontains a JSON array with at least one valid image record. If you are unfamiliar with editing catalogue files, restore a known-working copy or follow the plugin’s custom-gallery format.
第 <record number> 条素材须为对象。
- Explanation: A catalogue entry is not a JSON object containing named fields. For example, a plain string in the array cannot serve as a complete image record.
- Solution: Correct the indicated entry so it uses the same object structure as a working catalogue record, including its identifier, pose metadata, and image reference.
第 <record number> 条素材缺少文本字段:<field name>
- Explanation: The indicated catalogue record is missing a required nonempty text field, or that field has the wrong data type. The required fields are
id,体系,姿势编号,分类,姿势名称,角度, and原图. - Solution: Add or correct the named field in the indicated record. Make sure its value is text and is not empty or composed only of spaces, then retry loading the gallery.
Selected image ID is unavailable in the active gallery
- Explanation: This is a descriptive troubleshooting label, not a quoted error message from the supplied source. The node must look up
pose_idin the selected catalogue, so an outdated, mistyped, or source-mismatched identifier can prevent it from loading the reference. - Solution: Confirm
asset_source, reopen the gallery, and select the image again. If you changed custom catalogues, choose an identifier that exists in the current catalogue.
Custom catalogue contains duplicate IDs or an unsafe image path
- Explanation: This is a descriptive troubleshooting label; the exact error strings are not supplied. The provided tests confirm rejection of duplicate records with the same ID and image paths that attempt to escape the gallery directory, such as
../outside.png. - Solution: Give each image record a unique
idand keep its referenced image within the gallery directory using a valid internal path. Correct the catalogue entry rather than attempting to bypass its validation.
