Implementation:Datajuicer Data juicer ImageSAM3DBodyMapper

Knowledge Sources	Datajuicer_Data_juicer
Domains	Data_Processing, Mapping
Last Updated	2026-02-14 16:00 GMT

Overview

Concrete tool for performing single-image full-body 3D human mesh recovery using SAM 3D Body provided by Data-Juicer.

Description

ImageSAM3DBodyMapper is a mapper operator that performs 3D human mesh recovery (HMR) from single images using the SAM 3D Body promptable model. It integrates multiple specialized models: a human detector (VitDet), a segmentor (SAM2), and a field-of-view estimator (MoGe2), along with the SAM 3D Body checkpoint. The operator automatically installs required packages, clones the SAM 3D Body repository, and configures model paths. It processes each image to detect humans, segment them, estimate camera FOV, and reconstruct 3D body meshes. Results are stored in a configurable metadata field. Supports optional visualization output and requires CUDA acceleration.

Usage

Use when you need to extract full-body 3D mesh data from single images for human-centric datasets in pose estimation, motion analysis, and 3D avatar generation pipelines.

Code Reference

Source Location

• Repository: Datajuicer_Data_juicer
• File: data_juicer/ops/mapper/image_sam_3d_body_mapper.py

Signature

@OPERATORS.register_module("image_sam_3d_body_mapper")
class ImageSAM3DBodyMapper(Mapper):
    def __init__(self,
                 checkpoint_path: str = "",
                 detector_name: str = "vitdet",
                 segmentor_name: str = "sam2",
                 fov_name: str = "moge2",
                 mhr_path: str = "",
                 detector_path: str = "",
                 segmentor_path: str = "",
                 fov_path: str = "",
                 bbox_thresh: float = 0.8,
                 use_mask: bool = False,
                 visualization_dir: str = None,
                 tag_field_name: str = "sam_3d_body_data",
                 *args, **kwargs):

Import

from data_juicer.ops.mapper.image_sam_3d_body_mapper import ImageSAM3DBodyMapper

I/O Contract

Inputs

Name	Type	Required	Description
checkpoint_path	str	Yes	Path to SAM 3D Body model checkpoint
detector_name	str	No	Human detection model name, defaults to "vitdet"
segmentor_name	str	No	Human segmentation model name, defaults to "sam2"
fov_name	str	No	FOV estimation model name, defaults to "moge2"
mhr_path	str	No	Path to MoHR/assets folder
detector_path	str	No	Path to human detection model folder
segmentor_path	str	No	Path to human segmentation model folder
fov_path	str	No	Path to FOV estimation model folder
bbox_thresh	float	No	Bounding box detection threshold, defaults to 0.8
use_mask	bool	No	Use mask-conditioned prediction, defaults to False
visualization_dir	str	No	Directory to save visualization results; if None, no visualization is saved
tag_field_name	str	No	Field name for storing results, defaults to "sam_3d_body_data"

Outputs

Name	Type	Description
samples	Dict	Transformed samples with 3D body mesh data stored in meta field

Usage Examples

process:
  - image_sam_3d_body_mapper:
      checkpoint_path: "/path/to/sam3d_checkpoint.pth"
      bbox_thresh: 0.8
      use_mask: false

Related Pages

• Environment:Datajuicer_Data_juicer_Python_Runtime_Environment