Fast Ref
/
Getting Started
Installation & Quick Start
설치 & 빠른 시작
요구 사항
- 3ds Max 2022 – 2025
- Fast Ref 공식
.mzp인스톨러로 설치 완료 - 유효한 Fast Ref 라이센스
임포트 — 경로 설정 필수
3ds Max의 Python 환경은 Fast Ref 패키지 경로를 자동으로 인식하지 않습니다. from os_fast_ref.api import FastRefAPI 를 바로 실행하면 아래 오류가 발생합니다:
ModuleNotFoundError: No module named 'os_fast_ref'import 전에 반드시 패키지 경로를 `sys.path`에 추가해야 합니다.
권장 — 3ds Max API로 자동 경로 추가
3ds Max는 pymxs.runtime.getDir() API로 현재 실행 중인 버전의 scripts 폴더 경로를 직접 반환합니다. 버전이 바뀌어도 코드 수정 없이 동작합니다.
import sys
import os
import pymxs
# 3ds Max가 현재 실행 버전의 userScripts 폴더를 직접 반환
scripts_dir = pymxs.runtime.getDir(pymxs.runtime.Name("userScripts"))
fast_ref_path = os.path.join(scripts_dir, "os_fast_ref_package")
if fast_ref_path not in sys.path:
sys.path.append(fast_ref_path)
from os_fast_ref.api import FastRefAPIgetDir("userScripts") 반환 예시:
C:\Users\cheoljin kim\AppData\Local\Autodesk\3dsMax\2025 - 64bit\ENU\scripts실제 설치 경로:
...\scripts\os_fast_ref_package\ ← sys.path에 추가하는 폴더
└── os_fast_ref\ ← import 대상 패키지함수로 만들어 재사용하기
여러 스크립트에서 반복 사용할 경우 아래처럼 함수로 정리해두면 편합니다.
import sys
import os
import pymxs
def import_fast_ref_api():
"""Fast Ref API를 경로 설정과 함께 임포트"""
scripts_dir = pymxs.runtime.getDir(pymxs.runtime.Name("userScripts"))
fast_ref_path = os.path.join(scripts_dir, "os_fast_ref_package")
if fast_ref_path not in sys.path:
sys.path.append(fast_ref_path)
from os_fast_ref.api import FastRefAPI
return FastRefAPI
FastRefAPI = import_fast_ref_api()
api = FastRefAPI()초기화
FastRefAPI() 인스턴스를 생성하면 자동으로 두 가지 작업이 실행됩니다:
1. 라이센스 인증 — 라이센스가 유효하지 않으면 PermissionError 발생 2. 씬 데이터 로드 — InfoNode에서 현재 씬의 레퍼런스 데이터를 로드
api = FastRefAPI()초기화 실패 시:
# 라이센스가 없거나 유효하지 않을 때
# → PermissionError: 🔐 라이센스 인증에 실패했습니다.
# 라이센스 모듈이 없을 때 (설치 오류)
# → ImportError: 🔐 Fast_Ref 라이센스 시스템이 누락되었습니다.빠른 시작 예제
이후 예제는 경로 설정이 완료된 상태를 가정합니다. 각 스크립트 상단에 아래 코드를 추가하세요:
import sys, os, pymxs
_p = os.path.join(pymxs.runtime.getDir(pymxs.runtime.Name("userScripts")), "os_fast_ref_package")
if _p not in sys.path: sys.path.append(_p)씬 레퍼런스 목록 조회
from os_fast_ref.api import FastRefAPI
api = FastRefAPI()
refs = api.get_reference_list()
print(f"씬에 레퍼런스 {refs['count']}개")
for ref in refs['data']:
print(f" [{ref['slot']}] {ref['name']} ({ref['namespace']})")파일 상태 확인
status = api.check_file_status()
for s in status['data']:
print(f" {s['name']}: {s['status']}")
# status: "latest" / "outdated" / "missing" / "converted"레퍼런스 추가
result = api.add_reference(r"J:\assets\character.max")
if result['success']:
print(f"슬롯 {result['slot']}에 추가됨")레퍼런스 교체
result = api.replace_reference(slot=0, new_file=r"J:\assets\character_v2.max")FBX 내보내기 (단일)
result = api.export_fbx(
slot=0,
output_path=r"J:\output\character.fbx"
)FBX 내보내기 (옵션 지정)
result = api.export_fbx(
slot=0,
output_path=r"J:\output\character_no_anim.fbx",
fbx_options={
"Animation": False,
"BakeAnimation": False,
}
)FBX 전체 일괄 내보내기
result = api.export_fbx_all(output_folder=r"J:\output")
print(f"성공: {result['exported_count']}, 실패: {result['failed_count']}")파이프라인 전체 흐름 예제
import sys, os, pymxs
_p = os.path.join(pymxs.runtime.getDir(pymxs.runtime.Name("userScripts")), "os_fast_ref_package")
if _p not in sys.path: sys.path.append(_p)
from os_fast_ref.api import FastRefAPI
api = FastRefAPI()
# 1. 파일 상태 확인
status = api.check_file_status()
outdated = [s for s in status['data'] if s['status'] == 'outdated']
# 2. 변경된 레퍼런스가 있으면 전체 리로드
if outdated:
api.reload_all_references()
# 3. 전체 FBX 내보내기 (Root 0,0,0 리셋 포함)
result = api.export_fbx_all(
output_folder=r"J:\pipeline\output",
fbx_options={
"ResetRoot": True,
"ResetRootMode": "manual",
"ResetRootName": "Root",
"ResetAxisX": 0.0,
"ResetAxisY": 0.0,
"ResetAxisZ": 0.0,
}
)
for r in result['results']:
status_str = "OK" if r['success'] else "FAIL"
print(f" [{r['slot']}] {r['name']}: {status_str}")
# 4. Fast Ref UI 갱신 (UI가 열려 있는 경우)
api.update_ui()주의 사항
- API는 현재 3ds Max에 열린 씬에서 동작합니다. 대상 씬을 먼저 열어두고 호출하세요.
- 쓰기 작업은 씬을 직접 수정합니다. 변경 사항을 유지하려면 씬 파일을 수동으로 저장하세요.
- Fast Ref UI가 열려 있는 상태에서 API 작업을 마친 후 화면을 동기화하려면
api.update_ui()를 호출하세요.