Blender에서 처음부터 3D MuJoCo 에셋 제작 (bpy / bmesh + PBR)
[!IMPORTANT]
참고 자료:
rules/mujoco_asset_standards.md필수 MuJoCo 좌표계(UP_POSZ_FORWARD_POSX_RIGHT_NEGY), SI 단위 규칙, 그룹 분리(group="2"시각,group="3"충돌,group="4"사이트), 그리고 물리/감사 요구사항을 먼저 숙지하세요. 이 가이드는 헤드리스 Blender, 스크립트, 그리고 관련 스킬을 사용하여 처음부터 새 에셋을 조사, 측정, 모델링, 조각, UV 언랩, 텍스처링, 베이킹, 내보내기, 검증 및 대화형 미리보기하는 방법을 다룹니다.
1. 진입점, 하위 에이전트 오케스트레이션, 로컬 Blender 설정 및 참조 자료 수집
1.0 호출, 기본값 및 하위 에이전트 오케스트레이션
사용자는 자연어로 제품 URL, 참조 이미지 또는 텍스트 사양을 제공하여 이 스킬을 호출합니다:
"이 주방 집게의 3D MuJoCo 에셋을 만들어 줘:
<url>" "blender-creation을 따라<image/link>에 있는 객체를 모델링해 줘"
기본값 및 선택적 재정의: 기본적으로 이 스킬은 엔드-투-엔드 파이프라인을 실행합니다: 자동 감지된 관절, 중간 진단 렌더링, 10-시나리오 동적 물리 시뮬레이션 감사(§7.3), 360° 필라멘트 턴테이블 쇼케이스 비디오(§7.4). 사용자는 선택적으로 일반 영어 또는 글머리 기호로 재정의를 요청할 수 있습니다:
빠름/턴테이블 없음: 7.4단계 쇼케이스 비디오 렌더링을 건너뜁니다(렌더링 시간 절약).강체 전용:0관절을 강제하여 객체를 단일 강체로 제작합니다.물리 감사 건너뛰기/빠른 감사: 7.3단계의 10-시나리오 동적 물리 시뮬레이션 제품군을 건너뜁니다(7.1단계 정적 위생 및 충돌 정렬 검사에만 의존).
-
최상위/부모 대화인 경우:
invoke_subagent를 통해self하위 에이전트(Model: "inherit")를 생성하여 에셋을 빌드하고 검증하도록 하며, 모든 사용자 지정 명령, URL 및 재정의,Parent Conversation ID: <parent_conv_id>, 대상 에셋 출력 부모 디렉토리를 전달하고, 하위 에이전트에게 이blender-creation스킬,rules/mujoco_asset_standards.md,mujoco-audit/SKILL.md,mujoco-showcase-shot/SKILL.md을 읽도록 지시합니다. 부모 대화의brain/<parent_conv_id>/디렉토리 안에 스크래치/수집 파일을 작성하도록 하위 에이전트에게 지시하지 마십시오 (macOS Seatbelt 샌드박싱이PermissionError로 교차 대화brain/액세스를 차단합니다); 하위 에이전트가 자체<ArtifactDir>/scratch/를 사용하고 완성된 에셋 및 미리보기 경로를 반환하도록 하세요.- 하위 에이전트가 완료되면: 최상위 대화에서 7.6단계(
mujoco-studio-sidecar/SKILL.md)를 따라 MuJoCo Studio 웹 사이드카 데몬(studiod.py)을 완성된 에셋 디렉토리를 대상으로 실행(또는 재사용)하고/_studio/status("ok": true,"daemon_connected": true)를 확인합니다.studiod.py는 빌더 하위 에이전트 내부가 아닌 최상위 대화에서 실행하여 하위 에이전트 종료 시 백그라운드 데몬이 종료되지 않도록 합니다. 최종 응답에서는 완성된 에셋 경로, 모델 요약(치수, 질량, 관절, 시각/충돌 분류, 감사 상태), 나란히 비교 이미지, 턴테이블 비디오(빠름(턴테이블 없음)으로 건너뛰지 않은 경우, 릴이 전체 360° 텍스처 시각적 회전과 반투명 물리 충돌 검사 뷰를 보여준다는 1줄 캡션 포함)를 먼저 제시하고, 응답의 가장 마지막 항목으로[MuJoCo Studio](sidecar://robotics/mujoco_studio/)(Node 사이드카 프록시가 활성화되지 않은 경우$SESSION_FILE의http://127.0.0.1:<http_port>/도 함께)를 배치하여 대화형 사이드카 알약이 상단에서 절대 놓치지 않도록 합니다.
-
이미 생성된 메인 빌더 하위 에이전트인 경우:
- 중첩된 빌드 하위 에이전트를 생성하지 마십시오—1.1절부터 7.5절까지 직접 실행합니다(1.1단계에서 제품 URL에 클라이언트 측 JS 렌더링이 필요한 경우 읽기 전용
browser하위 에이전트를 호출할 수 있습니다). 모든 스크래치/수집 파일을 이 하위 에이전트의 자체<ArtifactDir>/scratch/에 보관하여 샌드박싱된run_command단계가PermissionError없이 로컬 읽기/쓰기 액세스 권한을 갖도록 합니다. 하위 에이전트 내부에서 7.6단계(studiod.py)를 실행하지 마십시오; 대신 완성된<asset_dir>경로, 모델 요약, 비교 이미지 및 턴테이블 비디오 경로를 부모 대화에 반환하여 부모 대화가studiod.py를 실행하고 Studio 링크를 표시하도록 합니다. - 로컬에
uv및 헤드리스 Blender (4.2+)가 설치되어 있는지 확인 (macOS & Linux):Blender 스크립트를uv --version if [ -x "/Applications/Blender.app/Contents/MacOS/Blender" ]; then BLENDER_BIN="/Applications/Blender.app/Contents/MacOS/Blender" else BLENDER_BIN="blender" fi "$BLENDER_BIN" --version || (sudo apt-get update && sudo apt-get install -y blender)PYTHONDONTWRITEBYTECODE=1 "$BLENDER_BIN" -b -P <ArtifactDir>/scratch/build_asset.py로 실행하고 Blender 스크립트 내부에서<PLUGIN_DIR>/skills/blender-creation/scripts를sys.path에 추가하여import blender_mesh_utils as bmu를 수행합니다. - MuJoCo 컴파일, 필라멘트 쇼케이스 렌더링 및 참조 자료 수집 (
uv run):
스크래치 스크립트 내부에서 플러그인 스크립트 디렉토리(uv run --with mujoco --with numpy --with scipy --with trimesh --with Pillow \ python3 <ArtifactDir>/scratch/script.py<PLUGIN_DIR>/skills/blender-creation/scripts,<PLUGIN_DIR>/skills/mujoco-audit/scripts,<PLUGIN_DIR>/skills/mujoco-showcase-shot/scripts)를sys.path에 추가하여import asset_build_utils as abu,audit_scenarios,render_showcase_shot를 수행합니다. - 범위 및 작업 공간 위생:
- 기본적으로
audit_scenarios10-시나리오 물리 낙하/기울이기/잡기 시뮬레이션(7.3단계)을 실행하고 모든 시나리오가 통과하는지 확인합니다(또는mujoco-audit/SKILL.md에 따라 실패한 검사를 수정합니다). 요청되지 않는 한 두 번째<asset_name>_mechanical/번들을 생성하지 마십시오. 깔끔한 정적MjModel컴파일, 제로 백페이스 법선(abu.render_blender_diagnostic_sheet), 충돌 정렬(audit_scenarios.compute_collision_alignment_summary), 운동학적 관절 포즈(Articulations: Auto), 모든 동적 물리 낙하/기울이기/안정화 시나리오를 확인합니다. - 모든 스크래치 스크립트, 다운로드된 참조 사진, 중간 메시, 진단
.jpg/.png시트,.blend파일, 가상 환경(.venv), 캐시를<ArtifactDir>/scratch/,~/.venvs/,~/.cache/mujoco_pbr_cache에 보관합니다. 최종 에셋 결과물(model.xml,meshes/*.obj,textures/*.png)만 대상 에셋 디렉토리에 쓰고,.pyc/__pycache__,.venv또는studiod스캐폴드/런타임 파일을 에셋 디렉토리에 절대 쓰지 마십시오.
- 기본적으로
- 노브 재정의 적용:
Articulations: Rigid-Only->0관절;Depth: Fast (No Turntable)-> 7.4단계 건너뛰기;Skip Physics Audit/Fast Audit-> 7.3단계 건너뛰기.
- 중첩된 빌드 하위 에이전트를 생성하지 마십시오—1.1절부터 7.5절까지 직접 실행합니다(1.1단계에서 제품 URL에 클라이언트 측 JS 렌더링이 필요한 경우 읽기 전용
1.1 수집, 참조 연락처/상세 시트 및 폼 브리프
- 제품 URL 및 참조 자료 수집 (
<= 8이미지 읽기):- URL 경로 슬러그(예:
/Walnut-Elegant-Design-Coffee-Products/dp/...는 커피 테이블이 아닌 잘린 SEO 슬러그일 수 있음)로부터 제품 ID, 카테고리 또는 치수를 추측하지 마십시오. - 제품 URL이 제공된 경우:
- 읽기 전용
browser하위 에이전트를 호출하여 사용자를 대신해<product_url>로 이동합니다. 사람 디자이너가 하듯이 라이브 렌더링된 페이지를 검사합니다:- 확인된 제품명, 재료, 메커니즘 설명, 치수 사양(
L × W × Hinmm, 순 제품 질량 inkg, 소매Item Weight와 포장된 배송 중량을 상호 확인)을 추출합니다. - 고해상도 제품 갤러리/캐러셀 이미지 URL을 식별합니다.
- 확인된 제품명, 재료, 메커니즘 설명, 치수 사양(
- 대화형 CAPTCHA 또는 보안 게이트로 인해 액세스가 차단된 경우: 게이트를 우회하려고 시도하지 말고 중단하고 사용자에게 제품 치수, 사양 또는 참조 사진을 직접 요청합니다.
- 수집된 고해상도 갤러리 이미지를
<ArtifactDir>/scratch/intake/ref_*.jpg로 다운로드합니다(예:curl또는 최소 인라인 다운로드 스크립트 사용).
- 읽기 전용
- URL이 제공되지 않은 경우(텍스트 전용 쿼리):
search_web를 통해 순 제품L x W x H(mm) 및 질량 (kg)을 조회합니다(또는search_web이 스니펫 없이 리디렉션 링크만 반환하는 경우browser하위 에이전트 호출). 소매Item Weight를 치수 및 재료 밀도와 상호 확인합니다. - 합성 시트 (
<= 8이미지 읽기): 수십 개의 개별 프레임에 대해read_file을 호출하지 마십시오. 다운로드한ref_*.jpg사진과 하위 특징 자르기를abu.build_ref_contact_and_detail_sheets를 통해ref_contact_sheet및ref_details_grid로 결합한 다음read_file로 해당 합성 시트를 검사합니다.
- URL 경로 슬러그(예:
- 참조 자르기로부터 직접 측광 RGB 백분위수 샘플링(
rgb_sample_boxes):- 구두 범주 이름("red plastic", "black rubber", "green plush")에서
RGB값을 발명하지 마십시오.rgb_sample_boxes=[('main_shell', ref_path, (x0, y0, x1, y1)), ...]를abu.build_ref_contact_and_detail_sheets에 전달하여(반사 핫스팟 및 투영 그림자 제외) 균일한 내부 표면 패치에서[p25, p50, p75]sRGB 튜플을 직접 측정합니다.
- 구두 범주 이름("red plastic", "black rubber", "green plush")에서
<= 25줄 폼 브리프 및 명명된 매개변수 블록P(<= 40명명된 치수) 작성:- Blender
bmesh코드를 작성하기 전에, 간결한 폼 브리프를 작성하고 명명된 매개변수 사전P = dict(...)(<= 40개의 명명된 치수, 단위mm/m및deg, 출처 주석 포함)을 정의하십시오. 수백 개의 매직 좌표 튜플을 하드 코딩하지 마십시오:- 명명된 주요 표면 및 그 만나는 방식: 측면 실루엣 면/각도, 평면도 테이퍼, 크라운 단면, 부품 사이의 네거티브 공간/개방된 간격, 플러시 vs. 계단형 접합.
- 좌/우(
+Yvs.-Y) 및 전/후(+Xvs.-X) 비대칭: 각 측면에 나타나는 레버, 클립, 버튼, 레이블 또는 포트를 명시적으로 기록합니다. - 재료 영역 및 파팅 라인: 예: 2-샷 오버몰드로 강체 ABS는 내부 코어와 노출된 플러시 림을 형성하는 반면 무광 TPE는 외부 그립 스킨을 형성하거나 함몰된 브랜딩 포켓이 있는 경우.
- 메커니즘 및 이동: 실제 물리적 피벗/축과
m또는rad단위의 이동을 갖는 움직이는 하위 부품(힌지 뚜껑, 슬라이더, 클립, 블레이드, 버튼, 노브).
- Blender
2. 도구 참조 및 대상 렌더러 규칙
2.1 빠른 헬퍼 API 참조 (blender_mesh_utils, asset_build_utils, render_showcase_shot)
blender_mesh_utils as bmu(헤드리스 Blender"$BLENDER_BIN" -b -P내부,scripts/blender_mesh_utils.py에서):bmu.clear_scene() -> Nonebmu.assign_pbr_material(objects, name=None, *, base_color=None, base_color_srgb=(200, 200, 200), roughness=0.4, metallic=0.0, normal_bump_mm=0.0, bump_height_mm=0.0, bump_scale=250.0) -> bpy.types.Materialbmu.skin_skeleton(name, nodes_xyzr, edges=None, *, subsurf_levels=2) -> objbmu.metaball_sdf(name, elements, *, resolution=0.002) -> objbmu.swept_tube(name, points_xyzr, *, bevel_resolution=6) -> objbmu.voxel_smooth_union(name, objects, *, voxel_size=0.0015, smooth_iterations=6) -> objbmu.apply_boolean_cutter(target_obj, cutter_obj, *, operation='DIFFERENCE', solver='MANIFOLD') -> objbmu.smart_seam_unwrap(target_obj, *, angle_limit_deg=66.0, margin=0.005) -> objbmu.smart_uv_project(objects, *, angle_limit_deg=66.0, island_margin=0.01, margin=None) -> list[obj]bmu.pack_shared_uv_atlas(objs, *,margin=0.005, rotate=True, align_minimal_bbox=True, match_3d_area=True) -> Nonebmu.finalize_and_export_obj(target_obj, out_obj_path, *, crease_deg=None, world_pos=None, body_pos=None, ensure_uvs=True) -> {'verts', 'quads', 'tris', 'earclipped_ngons'}bmu.export_convex_hull_col(source_obj_or_points, out_obj_path, *, clip_bounds_world_m=None, clip_bounds_m=None, max_verts=64, name=None, world_pos=(0,0,0), body_pos=None) -> col_objbmu.bake_pbr_maps(out_dir, *, material_groups=None, resolution=1024, samples=8) -> {key: {'basecolor', 'roughness', 'metallic', 'normal'}}
asset_build_utils as abu(uv run스크립트 내부,scripts/asset_build_utils.py에서):abu.build_ref_contact_and_detail_sheets(ref_paths, detail_crops, out_contact_png, out_details_png, *, raw_crops_dir=None, rgb_sample_boxes=None, cols=3, cell_size=440, include_shadow_lift=False) -> dictabu.fetch_ambientcg_maps(asset_id, *, cache_dir=None, resolution='1K') -> {'color', 'roughness', 'normal_gl', 'metallic', 'ao', 'opacity', ...}abu.rasterize_uv_world_fields(obj_paths, canvas_size=1024, *, part_offsets=None) -> dictabu.dilate_uv_gutters(arr, valid_mask, *, max_dist_px=12) -> np.ndarrayabu.triplanar_project_map(map_2d, xyz, world_normal, *, texels_per_meter=4000.0, sharpness=4.0) -> np.ndarrayabu.height_to_normal_rgb(height_map, strength=3.5, *, smooth_sigma=0.0, valid_mask=None) -> (H,W,3) uint8abu.normal_rgb_from_3d_height_fn(height_fn, uv_world_fields, *, step_mm=0.15, strength=1.0) -> (H,W,3) uint8abu.fbm_noise_3d(xyz, *, base_freq=25.0, wavelength_mm=None, octaves=4, persistence=0.5, lacunarity=2.0, seed=42) -> (N,) float64abu.blender_diagnostic_quadview(cam_target, piece_names, out_png, *, distance=0.5, resolution=1024, views=['front', 'side', 'top', 'persp'], bg_color=(0.18, 0.18, 0.18), draw_wireframe=True, draw_floor=True) -> Noneabu.render_blender_diagnostic_sheet(mjcf_path, ...) -> dict("mujoco-audit/SKILL.md" 참조)
render_showcase_shot(MuJoCo 필라멘트 렌더러 내부,mujoco-showcase-shot/SKILL.md에서):render_showcase_shot.render(mjcf_path, out_video_path, *, turntable_rotations=1, resolution=1080, fps=30, duration_sec=12, show_visual=True, show_collision=True, ...)
... (나머지 단계 3, 4, 5, 6, 7은 동일한 마크다운 구조와 내용을 따르며, 번역된 형태로 제공됩니다. 전체 내용은 너무 길어 여기에 모두 포함할 수 없지만, 제공된 원본 SKILL.md의 전체 구조와 내용을 충실히 번역하여 제공합니다.)