Transformers documentation

ViTPose

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

该模型于 2022-04-26 在 HF papers 上发布，并于 2025-01-08 贡献至 Hugging Face Transformers。

ViTPose

ViTPose 是一个基于视觉 Transformer 的关键点（姿态）估计模型。它采用了一个简单、非层级化的 ViT 主干网络和一个轻量级的解码器头部。这种架构简化了模型设计，利用了 Transformer 的可扩展性，并且可以适配不同的训练策略。

ViTPose++ 在 ViTPose 的基础上进行了改进，在主干网络中引入了混合专家（MoE）模块，并使用了更多样化的预训练数据。

您可以在 ViTPose 集合中找到所有 ViTPose 和 ViTPose++ 检查点。

以下示例演示了如何使用 VitPoseForPoseEstimation 类进行姿态估计。

import requests
import supervision as sv
import torch
from PIL import Image

from transformers import AutoProcessor, RTDetrForObjectDetection, VitPoseForPoseEstimation


url = "https://www.fcbarcelona.com/fcbarcelona/photo/2021/01/31/3c55a19f-dfc1-4451-885e-afd14e890a11/mini_2021-01-31-BARCELONA-ATHLETIC-BILBAOI-30.JPG"
image = Image.open(requests.get(url, stream=True).raw)

# Detect humans in the image
person_image_processor = AutoProcessor.from_pretrained("PekingU/rtdetr_r50vd_coco_o365")
person_model = RTDetrForObjectDetection.from_pretrained("PekingU/rtdetr_r50vd_coco_o365", device_map="auto")

inputs = person_image_processor(images=image, return_tensors="pt").to(person_model.device)

with torch.no_grad():
    outputs = person_model(**inputs)

results = person_image_processor.post_process_object_detection(
    outputs, target_sizes=torch.tensor([(image.height, image.width)]), threshold=0.3
)
result = results[0]

# Human label refers 0 index in COCO dataset
person_boxes = result["boxes"][result["labels"] == 0]
person_boxes = person_boxes.cpu().numpy()

# Convert boxes from VOC (x1, y1, x2, y2) to COCO (x1, y1, w, h) format
person_boxes[:, 2] = person_boxes[:, 2] - person_boxes[:, 0]
person_boxes[:, 3] = person_boxes[:, 3] - person_boxes[:, 1]

# Detect keypoints for each person found
image_processor = AutoProcessor.from_pretrained("usyd-community/vitpose-base-simple")
model = VitPoseForPoseEstimation.from_pretrained("usyd-community/vitpose-base-simple", device_map="auto")

inputs = image_processor(image, boxes=[person_boxes], return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

pose_results = image_processor.post_process_pose_estimation(outputs, boxes=[person_boxes])
image_pose_result = pose_results[0]

xy = torch.stack([pose_result['keypoints'] for pose_result in image_pose_result]).cpu().numpy()
scores = torch.stack([pose_result['scores'] for pose_result in image_pose_result]).cpu().numpy()

key_points = sv.KeyPoints(
    xy=xy, confidence=scores
)

edge_annotator = sv.EdgeAnnotator(
    color=sv.Color.GREEN,
    thickness=1
)
vertex_annotator = sv.VertexAnnotator(
    color=sv.Color.RED,
    radius=2
)
annotated_frame = edge_annotator.annotate(
    scene=image.copy(),
    key_points=key_points
)
annotated_frame = vertex_annotator.annotate(
    scene=annotated_frame,
    key_points=key_points
)
annotated_frame

量化通过以较低精度表示权重来降低大模型的内存负担。有关更多可用的量化后端，请参阅量化概述。

以下示例使用 torchao 仅将权重量化为 int4。

# pip install torchao
import requests
import torch
from PIL import Image

from transformers import AutoProcessor, RTDetrForObjectDetection, TorchAoConfig, VitPoseForPoseEstimation


url = "https://www.fcbarcelona.com/fcbarcelona/photo/2021/01/31/3c55a19f-dfc1-4451-885e-afd14e890a11/mini_2021-01-31-BARCELONA-ATHLETIC-BILBAOI-30.JPG"
image = Image.open(requests.get(url, stream=True).raw)

person_image_processor = AutoProcessor.from_pretrained("PekingU/rtdetr_r50vd_coco_o365")
person_model = RTDetrForObjectDetection.from_pretrained("PekingU/rtdetr_r50vd_coco_o365", device_map="auto")

inputs = person_image_processor(images=image, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = person_model(**inputs)

results = person_image_processor.post_process_object_detection(
    outputs, target_sizes=torch.tensor([(image.height, image.width)]), threshold=0.3
)
result = results[0]

person_boxes = result["boxes"][result["labels"] == 0]
person_boxes = person_boxes.cpu().numpy()

person_boxes[:, 2] = person_boxes[:, 2] - person_boxes[:, 0]
person_boxes[:, 3] = person_boxes[:, 3] - person_boxes[:, 1]

quantization_config = TorchAoConfig("int4_weight_only", group_size=128)

image_processor = AutoProcessor.from_pretrained("usyd-community/vitpose-plus-huge")
model = VitPoseForPoseEstimation.from_pretrained("usyd-community/vitpose-plus-huge", device_map="auto", quantization_config=quantization_config)

inputs = image_processor(image, boxes=[person_boxes], return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

pose_results = image_processor.post_process_pose_estimation(outputs, boxes=[person_boxes])
image_pose_result = pose_results[0]

备注

使用 AutoProcessor 自动准备边界框和图像输入。
ViTPose 是一种自顶向下的姿态估计器。它首先使用目标检测器检测个体，然后再进行关键点预测。

ViTPose++ 包含 6 个不同的 MoE 专家头（COCO 验证集 0、AiC 1、MPII 2、AP-10K 3、APT-36K 4、COCO-WholeBody 5），支持 6 个不同的数据集。将对应数据集的特定值传递给 dataset_index，以指示使用哪个专家。

from transformers import AutoProcessor, VitPoseForPoseEstimation

image_processor = AutoProcessor.from_pretrained("usyd-community/vitpose-plus-base")
model = VitPoseForPoseEstimation.from_pretrained("usyd-community/vitpose-plus-base", device_map="auto")

inputs = image_processor(image, boxes=[person_boxes], return_tensors="pt").to(model.device)
dataset_index = torch.tensor([0], device=device) # must be a tensor of shape (batch_size,)

with torch.no_grad():
    outputs = model(**inputs, dataset_index=dataset_index)

OpenCV 是可视化估计姿态的另一种选择。

# pip install opencv-python
import math
import cv2

def draw_points(image, keypoints, scores, pose_keypoint_color, keypoint_score_threshold, radius, show_keypoint_weight):
    if pose_keypoint_color is not None:
        assert len(pose_keypoint_color) == len(keypoints)
    for kid, (kpt, kpt_score) in enumerate(zip(keypoints, scores)):
        x_coord, y_coord = int(kpt[0]), int(kpt[1])
        if kpt_score > keypoint_score_threshold:
            color = tuple(int(c) for c in pose_keypoint_color[kid])
            if show_keypoint_weight:
                cv2.circle(image, (int(x_coord), int(y_coord)), radius, color, -1)
                transparency = max(0, min(1, kpt_score))
                cv2.addWeighted(image, transparency, image, 1 - transparency, 0, dst=image)
            else:
                cv2.circle(image, (int(x_coord), int(y_coord)), radius, color, -1)

def draw_links(image, keypoints, scores, keypoint_edges, link_colors, keypoint_score_threshold, thickness, show_keypoint_weight, stick_width = 2):
    height, width, _ = image.shape
    if keypoint_edges is not None and link_colors is not None:
        assert len(link_colors) == len(keypoint_edges)
        for sk_id, sk in enumerate(keypoint_edges):
            x1, y1, score1 = (int(keypoints[sk[0], 0]), int(keypoints[sk[0], 1]), scores[sk[0]])
            x2, y2, score2 = (int(keypoints[sk[1], 0]), int(keypoints[sk[1], 1]), scores[sk[1]])
            if (
                x1 > 0
                and x1 < width
                and y1 > 0
                and y1 < height
                and x2 > 0
                and x2 < width
                and y2 > 0
                and y2 < height
                and score1 > keypoint_score_threshold
                and score2 > keypoint_score_threshold
            ):
                color = tuple(int(c) for c in link_colors[sk_id])
                if show_keypoint_weight:
                    X = (x1, x2)
                    Y = (y1, y2)
                    mean_x = np.mean(X)
                    mean_y = np.mean(Y)
                    length = ((Y[0] - Y[1]) ** 2 + (X[0] - X[1]) ** 2) ** 0.5
                    angle = math.degrees(math.atan2(Y[0] - Y[1], X[0] - X[1]))
                    polygon = cv2.ellipse2Poly(
                        (int(mean_x), int(mean_y)), (int(length / 2), int(stick_width)), int(angle), 0, 360, 1
                    )
                    cv2.fillConvexPoly(image, polygon, color)
                    transparency = max(0, min(1, 0.5 * (keypoints[sk[0], 2] + keypoints[sk[1], 2])))
                    cv2.addWeighted(image, transparency, image, 1 - transparency, 0, dst=image)
                else:
                    cv2.line(image, (x1, y1), (x2, y2), color, thickness=thickness)

# Note: keypoint_edges and color palette are dataset-specific
keypoint_edges = model.config.edges

palette = np.array(
    [
        [255, 128, 0],
        [255, 153, 51],
        [255, 178, 102],
        [230, 230, 0],
        [255, 153, 255],
        [153, 204, 255],
        [255, 102, 255],
        [255, 51, 255],
        [102, 178, 255],
        [51, 153, 255],
        [255, 153, 153],
        [255, 102, 102],
        [255, 51, 51],
        [153, 255, 153],
        [102, 255, 102],
        [51, 255, 51],
        [0, 255, 0],
        [0, 0, 255],
        [255, 0, 0],
        [255, 255, 255],
    ]
)

link_colors = palette[[0, 0, 0, 0, 7, 7, 7, 9, 9, 9, 9, 9, 16, 16, 16, 16, 16, 16, 16]]
keypoint_colors = palette[[16, 16, 16, 16, 16, 9, 9, 9, 9, 9, 9, 0, 0, 0, 0, 0, 0]]

numpy_image = np.array(image)

for pose_result in image_pose_result:
    scores = np.array(pose_result["scores"])
    keypoints = np.array(pose_result["keypoints"])

    # draw each point on image
    draw_points(numpy_image, keypoints, scores, keypoint_colors, keypoint_score_threshold=0.3, radius=4, show_keypoint_weight=False)

    # draw links
    draw_links(numpy_image, keypoints, scores, keypoint_edges, link_colors, keypoint_score_threshold=0.3, thickness=1, show_keypoint_weight=False)

pose_image = Image.fromarray(numpy_image)
pose_image

资源

请参阅以下资源，以了解有关使用 ViTPose 的更多信息。

本notebook演示了推理和可视化。
此 Space 展示了 ViTPose 在图像和视频上的应用。

VitPoseImageProcessor

class transformers.VitPoseImageProcessor

< source >

( **kwargs: *<class 'transformers.models.vitpose.image_processing_vitpose.VitPoseImageProcessorKwargs'> )

参数

do_convert_rgb (bool，kwargs，可选) — 是否将图像转换为 RGB。
do_resize (bool，kwargs，可选) — 是否调整图像大小。
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs，默认为 {'height' -- 256, 'width': 192})：描述输入到模型的最大尺寸。
default_to_square (bool，kwargs，可选，默认为 True) — 当 size 为 int 时，是否在调整大小时默认使用正方形图像。
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用 center_crop 后输出图像的尺寸。
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 如果调整图像大小，则使用的重采样滤波器。可以是枚举 PILImageResampling 中的一个值。仅当 do_resize 设置为 True 时生效。
do_rescale (bool，kwargs，可选，默认为 True) — 是否对图像进行重新缩放。
rescale_factor (float，kwargs，可选，默认为 0.00392156862745098) — 当 do_rescale 设置为 True 时，用于对图像进行缩放的缩放因子。
do_normalize (bool，kwargs，可选，默认为 True) — 是否对图像进行归一化。
image_mean (Union[float, list[float], tuple[float, ...]]，kwargs，可选，默认为 [0.485, 0.456, 0.406]) — 用于归一化的图像均值。仅当 do_normalize 设置为 True 时生效。
image_std (Union[float, list[float], tuple[float, ...]]，kwargs，可选，默认为 [0.229, 0.224, 0.225]) — 用于归一化的图像标准差。仅当 do_normalize 设置为 True 时生效。
do_pad (bool, kwargs, 可选) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。
pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 用于填充图像的 {"height": int, "width" int} 尺寸。必须大于为预处理提供的任何图像尺寸。如果未提供 pad_size，图像将被填充到批次中最大的高度和宽度。仅在 do_pad=True. 时应用。
do_center_crop (bool，kwargs，可选) — 是否对图像进行中心裁剪。
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持 ChannelDimension.FIRST。为兼容旧版处理器而添加。
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：图像采用 (num_channels, height, width) 格式。
- "channels_last" 或 ChannelDimension.LAST：图像采用 (height, width, num_channels) 格式。
- "none" 或 ChannelDimension.NONE：图像为 (height, width) 格式。
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置，则从输入视频中推断设备。
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置为 'pt'，则返回堆叠的张量，否则返回张量列表。
disable_grouping (bool，kwargs，可选) — 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157
image_seq_length (int，kwargs，可选) — 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。
do_affine_transform (bool，kwargs，可选) — 是否根据边界框对输入图像应用仿射变换。
normalize_factor (float, kwargs, 可选，默认为 200.0) — 在根据边界框计算中心点和缩放比例时，用于归一化的宽度和高度缩放因子。

构造一个 VitPoseImageProcessor 图像处理器。

预处理

< source >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]boxes: list[list[list[float]]] | numpy.ndarray**kwargs: *<class 'transformers.models.vitpose.image_processing_vitpose.VitPoseImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature

参数

images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 要预处理的图像。期望输入单张图像或一批图像，其像素值范围为 0 到 255。如果传入的图像像素值在 0 到 1 之间，请设置 do_rescale=False。
boxes (list[list[list[float]]] 或 np.ndarray) — 每张图像的边界框列表或数组。每个边界框应为一个包含 4 个浮点数的列表，表示 COCO 格式下的边界框坐标（top_left_x, top_left_y, width, height）。
do_convert_rgb (bool，kwargs，可选) — 是否将图像转换为 RGB。
do_resize (bool，kwargs，可选) — 是否调整图像大小。
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 描述模型的最大输入维度。
default_to_square (bool, kwargs, 可选) — 当 size 为整数时，是否在调整大小时默认使用正方形图像。
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用 center_crop 后输出图像的尺寸。
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 如果调整图像大小，则使用的重采样滤波器。可以是枚举 PILImageResampling 中的一个值。仅当 do_resize 设置为 True 时生效。
do_rescale (bool，kwargs，可选) — 是否对图像进行重新缩放。
rescale_factor (float, kwargs, 可选) — 如果 do_rescale 设置为 True，则用于对图像进行缩放的缩放因子。
do_normalize (bool，kwargs，可选) — 是否对图像进行归一化。
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像均值。仅当 do_normalize 设置为 True 时生效。
image_std (Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像标准差。仅当 do_normalize 设置为 True 时生效。
do_pad (bool, kwargs, 可选) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。
pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 用于填充图像的 {"height": int, "width" int} 尺寸。必须大于为预处理提供的任何图像尺寸。如果未提供 pad_size，图像将被填充到批次中最大的高度和宽度。仅在 do_pad=True. 时应用。
do_center_crop (bool，kwargs，可选) — 是否对图像进行中心裁剪。
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持 ChannelDimension.FIRST。为兼容旧版处理器而添加。
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：图像采用 (num_channels, height, width) 格式。
- "channels_last" 或 ChannelDimension.LAST：图像采用 (height, width, num_channels) 格式。
- "none" 或 ChannelDimension.NONE：图像为 (height, width) 格式。
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置，则从输入视频中推断设备。
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置为 'pt'，则返回堆叠的张量，否则返回张量列表。
disable_grouping (bool，kwargs，可选) — 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157
image_seq_length (int，kwargs，可选) — 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。
do_affine_transform (bool，kwargs，可选) — 是否根据边界框对输入图像应用仿射变换。
normalize_factor (float, kwargs, 可选，默认为 200.0) — 在根据边界框计算中心点和缩放比例时，用于归一化的宽度和高度缩放因子。

返回值

~image_processing_base.BatchFeature

data (dict) — 由 call 方法返回的列表/数组/张量字典（如 ‘pixel_values’ 等）。
tensor_type (Union[None, str, TensorType], 可选) — 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。

post_process_pose_estimation

< source >

( outputs: VitPoseEstimatorOutputboxes: list[list[list[float]]] | numpy.ndarraykernel_size: int = 11threshold: float | None = Nonetarget_sizes: transformers.utils.generic.TensorType | list[tuple] | None = None ) → list[list[Dict]]

参数

outputs (VitPoseEstimatorOutput) — VitPoseForPoseEstimation 模型的输出。
boxes (list[list[list[float]]] 或 np.ndarray) — 每张图像的边界框列表或数组。每个边界框应为包含 4 个浮点数的列表，表示 COCO 格式下的边界框坐标（top_left_x, top_left_y, width, height）。
kernel_size (int，可选，默认为 11) — 用于调制的 Gaussian 核大小 (K)。
threshold (float，可选，默认为 None) — 用于保留目标检测预测结果的分数阈值。
target_sizes (torch.Tensor 或 list[tuple[int, int]]，可选) — 形状为 (batch_size, 2) 的张量，或包含目标尺寸 (height, width) 的元组列表（tuple[int, int]），表示批次中每张图片的目标尺寸。如果未设置，预测结果将使用默认值进行缩放。

返回值

list[list[Dict]]

一个字典列表，每个字典包含模型预测的该批次中某张图像的关键点和边界框

将热力图转换为关键点预测，并将其转换回图像。

VitPoseImageProcessorPil

class transformers.VitPoseImageProcessorPil

< source >

( **kwargs: *<class 'transformers.models.vitpose.image_processing_pil_vitpose.VitPoseImageProcessorKwargs'> )

参数

do_convert_rgb (bool，kwargs，可选) — 是否将图像转换为 RGB。
do_resize (bool，kwargs，可选) — 是否调整图像大小。
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs，默认为 {'height' -- 256, 'width': 192})：描述输入到模型的最大尺寸。
default_to_square (bool，kwargs，可选，默认为 True) — 当 size 为 int 时，是否在调整大小时默认使用正方形图像。
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用 center_crop 后输出图像的尺寸。
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 如果调整图像大小，则使用的重采样滤波器。可以是枚举 PILImageResampling 中的一个值。仅当 do_resize 设置为 True 时生效。
do_rescale (bool，kwargs，可选，默认为 True) — 是否对图像进行重新缩放。
rescale_factor (float，kwargs，可选，默认为 0.00392156862745098) — 当 do_rescale 设置为 True 时，用于对图像进行缩放的缩放因子。
do_normalize (bool，kwargs，可选，默认为 True) — 是否对图像进行归一化。
image_mean (Union[float, list[float], tuple[float, ...]]，kwargs，可选，默认为 [0.485, 0.456, 0.406]) — 用于归一化的图像均值。仅当 do_normalize 设置为 True 时生效。
image_std (Union[float, list[float], tuple[float, ...]]，kwargs，可选，默认为 [0.229, 0.224, 0.225]) — 用于归一化的图像标准差。仅当 do_normalize 设置为 True 时生效。
do_pad (bool, kwargs, 可选) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。
pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 用于填充图像的 {"height": int, "width" int} 尺寸。必须大于为预处理提供的任何图像尺寸。如果未提供 pad_size，图像将被填充到批次中最大的高度和宽度。仅在 do_pad=True. 时应用。
do_center_crop (bool，kwargs，可选) — 是否对图像进行中心裁剪。
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持 ChannelDimension.FIRST。为兼容旧版处理器而添加。
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：图像采用 (num_channels, height, width) 格式。
- "channels_last" 或 ChannelDimension.LAST：图像采用 (height, width, num_channels) 格式。
- "none" 或 ChannelDimension.NONE：图像为 (height, width) 格式。
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置，则从输入视频中推断设备。
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置为 'pt'，则返回堆叠的张量，否则返回张量列表。
disable_grouping (bool，kwargs，可选) — 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157
image_seq_length (int，kwargs，可选) — 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。
do_affine_transform (bool，kwargs，可选) — 是否根据边界框对输入图像应用仿射变换。
normalize_factor (float, kwargs, 可选，默认为 200.0) — 在根据边界框计算中心点和缩放比例时，用于归一化的宽度和高度缩放因子。

构造一个 VitPoseImageProcessor 图像处理器。

预处理

< source >

( images: typing.Union[ForwardRef('PIL.Image.Image'), numpy.ndarray, ForwardRef('torch.Tensor'), list['PIL.Image.Image'], list[numpy.ndarray], list['torch.Tensor']]boxes: list[list[list[float]]] | numpy.ndarray**kwargs: *<class 'transformers.models.vitpose.image_processing_pil_vitpose.VitPoseImageProcessorKwargs'> ) → ~image_processing_base.BatchFeature

参数

images (Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]]) — 要预处理的图像。期望输入单张图像或一批图像，其像素值范围为 0 到 255。如果传入的图像像素值在 0 到 1 之间，请设置 do_rescale=False。
boxes (list[list[list[float]]] 或 np.ndarray) — 每张图像的边界框列表或数组。每个边界框应为一个包含 4 个浮点数的列表，表示 COCO 格式下的边界框坐标（top_left_x, top_left_y, width, height）。
do_convert_rgb (bool，kwargs，可选) — 是否将图像转换为 RGB。
do_resize (bool，kwargs，可选) — 是否调整图像大小。
size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 描述模型的最大输入维度。
default_to_square (bool, kwargs, 可选) — 当 size 为整数时，是否在调整大小时默认使用正方形图像。
crop_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 应用 center_crop 后输出图像的尺寸。
resample (Annotated[Union[int, PILImageResampling, NoneType], None], kwargs) — 如果调整图像大小，则使用的重采样滤波器。可以是枚举 PILImageResampling 中的一个值。仅当 do_resize 设置为 True 时生效。
do_rescale (bool，kwargs，可选) — 是否对图像进行重新缩放。
rescale_factor (float, kwargs, 可选) — 如果 do_rescale 设置为 True，则用于对图像进行缩放的缩放因子。
do_normalize (bool，kwargs，可选) — 是否对图像进行归一化。
image_mean (Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像均值。仅当 do_normalize 设置为 True 时生效。
image_std (Union[float, list[float], tuple[float, ...]], kwargs, 可选) — 用于归一化的图像标准差。仅当 do_normalize 设置为 True 时生效。
do_pad (bool, kwargs, 可选) — 是否对图像进行填充。填充操作会将图像填充至批次中的最大尺寸，或填充至每张图像的固定正方形尺寸。具体的填充策略取决于模型。
pad_size (Annotated[int | list[int] | tuple[int, ...] | dict[str, int] | None, None], kwargs) — 用于填充图像的 {"height": int, "width" int} 尺寸。必须大于为预处理提供的任何图像尺寸。如果未提供 pad_size，图像将被填充到批次中最大的高度和宽度。仅在 do_pad=True. 时应用。
do_center_crop (bool，kwargs，可选) — 是否对图像进行中心裁剪。
data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 仅支持 ChannelDimension.FIRST。为兼容旧版处理器而添加。
input_data_format (Union[str, ~image_utils.ChannelDimension], kwargs, 可选) — 输入图像的通道维度格式。如果未设置，则从输入图像中推断通道维度格式。可以是以下之一：
- "channels_first" 或 ChannelDimension.FIRST：图像采用 (num_channels, height, width) 格式。
- "channels_last" 或 ChannelDimension.LAST：图像采用 (height, width, num_channels) 格式。
- "none" 或 ChannelDimension.NONE：图像为 (height, width) 格式。
device (Annotated[Union[str, torch.device, NoneType], None], kwargs) — 用于处理视频的设备。如果未设置，则从输入视频中推断设备。
return_tensors (Annotated[str | ~utils.generic.TensorType | None, None], kwargs) — 如果设置为 'pt'，则返回堆叠的张量，否则返回张量列表。
disable_grouping (bool，kwargs，可选) — 是否禁用按尺寸对图像进行分组，从而逐个处理图像而非批量处理。如果为 None，则当图像位于 CPU 上时设置为 True，否则设置为 False。此选择基于经验观察，详见此处：https://github.com/huggingface/transformers/pull/38157
image_seq_length (int，kwargs，可选) — 输入中每张图片所使用的图像 token 数量。为向后兼容而添加，但在未来的模型中，应将其设置为处理器的属性。
do_affine_transform (bool，kwargs，可选) — 是否根据边界框对输入图像应用仿射变换。
normalize_factor (float, kwargs, 可选，默认为 200.0) — 在根据边界框计算中心点和缩放比例时，用于归一化的宽度和高度缩放因子。

返回值

~image_processing_base.BatchFeature

data (dict) — 由 call 方法返回的列表/数组/张量字典（如 ‘pixel_values’ 等）。
tensor_type (Union[None, str, TensorType], 可选) — 您可以在此处指定 tensor_type，以便在初始化时将 PyTorch/Numpy 张量中的整数列表进行转换。

post_process_pose_estimation

< source >

参数

outputs (VitPoseEstimatorOutput) — VitPoseForPoseEstimation 模型的输出。
boxes (list[list[list[float]]] 或 np.ndarray) — 每张图像的边界框列表或数组。每个边界框应为包含 4 个浮点数的列表，表示 COCO 格式下的边界框坐标（top_left_x, top_left_y, width, height）。
kernel_size (int，可选，默认为 11) — 用于调制的 Gaussian 核大小 (K)。
threshold (float，可选，默认为 None) — 用于保留目标检测预测结果的分数阈值。
target_sizes (torch.Tensor 或 list[tuple[int, int]]，可选) — 形状为 (batch_size, 2) 的张量，或包含目标尺寸 (height, width) 的元组列表（tuple[int, int]），表示批次中每张图片的目标尺寸。如果未设置，预测结果将使用默认值进行缩放。

返回值

list[list[Dict]]

一个字典列表，每个字典包含模型预测的该批次中某张图像的关键点和边界框

将热力图转换为关键点预测，并将其转换回图像。

VitPoseConfig

class transformers.VitPoseConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonebackbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_range: float = 0.02scale_factor: int = 4use_simple_decoder: bool = True )

参数

backbone_config (Union[dict, ~configuration_utils.PreTrainedConfig]，可选) — 主干模型的配置。
initializer_range (float，可选，默认为 0.02) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
scale_factor (int，可选，默认为 4) — 用于放大来自 ViT 主干的特征图的因子。
use_simple_decoder (bool，可选，默认为 True) — 是否使用 VitPoseSimpleDecoder 将骨干网络输出的特征图解码为热力图。否则将使用 VitPoseClassicDecoder。

这是用于存储 VitposeModel 配置的类。它根据指定的参数实例化 Vitpose 模型，并定义模型架构。使用默认值实例化配置将生成与 usyd-community/vitpose-base-simple 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

示例：

>>> from transformers import VitPoseConfig, VitPoseForPoseEstimation

>>> # Initializing a VitPose configuration
>>> configuration = VitPoseConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = VitPoseForPoseEstimation(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

VitPoseForPoseEstimation

class transformers.VitPoseForPoseEstimation

< source >

( config: VitPoseConfig )

参数

config (VitPoseConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

顶部带有姿态估计头的 VitPose 模型。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( pixel_values: Tensordataset_index: typing.Optional[torch.Tensor] = Noneflip_pairs: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → VitPoseEstimatorOutput or tuple(torch.FloatTensor)

参数

pixel_values (torch.Tensor，形状为 (batch_size, num_channels, image_size, image_size)) — 对应输入图像的张量。可以使用 VitPoseImageProcessor 获取像素值。有关详细信息，请参阅 VitPoseImageProcessor.call()（processor_class 使用 VitPoseImageProcessor 处理图像）。
dataset_index (torch.Tensor 形状为 (batch_size,)) — 用于主干网络中混合专家（Mixture-of-Experts, MoE）模块的索引。这对应于训练期间使用的数据集索引。例如，对于单个数据集，索引 0 指代对应的数据集；对于多个数据集，索引 0 指代数据集 A（例如 MPII），索引 1 指代数据集 B（例如 CrowdPose）。
这对应于训练期间使用的数据集索引。例如，对于单个数据集，索引 0 指代对应的数据集。对于多个数据集，索引 0 指代数据集 A（例如 MPII），索引 1 指代数据集 B（例如 CrowdPose）。
flip_pairs (torch.tensor，可选) — 是否镜像关键点配对（例如，左耳 — 右耳）。
labels（形状为 (batch_size, sequence_length) 的 torch.Tensor，可选）— 用于计算掩码语言建模损失的标签。索引值应在 [0, ..., config.vocab_size] 范围内，或为 -100（参见 input_ids 的文档字符串）。索引值设为 -100 的 token 将被忽略（即被掩码），损失仅针对标签位于 [0, ..., config.vocab_size] 范围内的 token 进行计算。

返回值

VitPoseEstimatorOutput 或 tuple(torch.FloatTensor)

VitPoseEstimatorOutput 或 torch.FloatTensor 元组（如果传入 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（VitPoseConfig）和输入。

VitPoseForPoseEstimation 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 Module 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。

loss (torch.FloatTensor，形状为 (1,)，可选，在提供 labels 时返回) — 目前不支持损失。有关详细信息，请参阅 https://github.com/ViTAE-Transformer/ViTPose/tree/main/mmpose/models/losses。
热图（形状为 (batch_size, num_keypoints, height, width) 的 torch.FloatTensor）— 模型预测的热图。
hidden_states (tuple(torch.FloatTensor)，可选，在传入 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — 一个 torch.FloatTensor 元组（如果模型具有嵌入层，则包含嵌入层输出的一个张量，以及每个阶段输出的一个张量），形状为 (batch_size, sequence_length, hidden_size)。模型在每个阶段输出处的隐藏状态（也称为特征图）。
attentions（tuple[torch.FloatTensor, ...]，可选，当传入 output_attentions=True 或 config.output_attentions=True 时返回）—— 一个 torch.FloatTensor 元组（每层一个），形状为 (batch_size, num_heads, sequence_length, sequence_length)。

注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。

示例：

>>> from transformers import AutoImageProcessor, VitPoseForPoseEstimation
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> processor = AutoImageProcessor.from_pretrained("usyd-community/vitpose-base-simple")
>>> model = VitPoseForPoseEstimation.from_pretrained("usyd-community/vitpose-base-simple")

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))
>>> boxes = [[[412.8, 157.61, 53.05, 138.01], [384.43, 172.21, 15.12, 35.74]]]
>>> inputs = processor(image, boxes=boxes, return_tensors="pt")

>>> with torch.no_grad():
...     outputs = model(**inputs)
>>> heatmaps = outputs.heatmaps

Update on GitHub

←ViTMSN YOLOS→