Fast Ref
/
Overview
Fast Ref API — Overview
Fast Ref — API 개요
Fast Ref API는 외부 스크립트에서 Fast Ref 워크플로를 자동화하기 위한 Python 인터페이스입니다. 파트너 스튜디오의 TA(Technical Artist)를 대상으로 설계되었습니다.
만든 배경
Fast Ref의 내장 UI 대신 자체 파이프라인 툴을 사용하는 TA를 지원하기 위해 만들어졌습니다. pymxs를 직접 다루는 별도 스크립트를 작성하는 대신, Fast Ref가 검증된 내부 기능을 Facade 패턴 인터페이스로 노출합니다.
설계 원칙
| 항목 | 방침 | 이유 |
|---|---|---|
| 읽기(READ) 작업 | UI 불필요 | 씬 InfoNode에서 직접 읽기 |
| 쓰기(WRITE) 작업 | UI 독립 | MainUI 없이 모든 작업 수행 |
| 데이터 로드 | 세션 내 캐시 활용 | 불필요한 씬 재로드 방지 |
| 다이얼로그 | 자동 억제 (silent_mode=True) |
자동화 중 팝업 차단 |
| FBX 옵션 | dict 기반 |
프리셋 파일 의존 없이 환경 독립 |
API 메서드 목록
| 카테고리 | 메서드 | 설명 |
|---|---|---|
| 조회 | get_reference_list() |
씬의 레퍼런스 목록 반환 |
| 조회 | check_file_status() |
소스 파일 최신/변경/누락 상태 확인 |
| 관리 | add_reference() |
레퍼런스 추가 |
| 관리 | remove_reference() |
레퍼런스 제거 |
| 관리 | replace_reference() |
레퍼런스 파일 교체 |
| 관리 | reload_reference() |
단일 레퍼런스 리로드 |
| 관리 | reload_all_references() |
전체 레퍼런스 리로드 |
| FBX 내보내기 | export_fbx() |
단일 레퍼런스 FBX 내보내기 |
| FBX 내보내기 | export_fbx_all() |
전체 레퍼런스 일괄 FBX 내보내기 |
| FBX 내보내기 | get_fbx_default_options() |
현재 FBX 옵션 기본값 조회 |
| 고급 | merge_reference() |
단일 레퍼런스를 씬 오브젝트로 변환 |
| 고급 | merge_all_references() |
전체 레퍼런스 일괄 변환 |
| 고급 | set_space_activate() |
네임스페이스 ON/OFF 전환 |
| 고급 | set_unpack() |
Unpack ON/OFF 전환 |
| 고급 | convert_to_reference() |
선택 오브젝트를 레퍼런스로 변환 |
| UI 연동 | update_ui() |
Fast Ref UI 수동 갱신 |
핵심 개념
슬롯 (Slot)
Fast Ref는 레퍼런스를 0~9번 슬롯으로 관리합니다. 하나의 슬롯에 하나의 레퍼런스가 할당되며, 쓰기 작업은 모두 슬롯 번호를 지정해서 호출합니다.
refs = api.get_reference_list()
for ref in refs['data']:
print(ref['slot'], ref['name']) # 0 캐릭터A, 1 캐릭터B, ...Space Activate
레퍼런스의 네임스페이스 적용 여부를 제어합니다. OFF 상태에서는 노드, 레이어, SelectionSet 이름에서 네임스페이스 접두사가 제거됩니다. FBX 내보내기나 외부 핸드오프 전에 주로 사용합니다.
Unpack
레퍼런스 노드들을 최상위 그룹 컨테이너에서 분리해 월드로 꺼냅니다. 특정 내보내기 워크플로에서 필요합니다.
InfoNode
Fast Ref는 모든 레퍼런스 메타데이터를 __FastRef_InfoNode라는 숨겨진 3dsMax 노드에 저장합니다. API는 이 노드를 직접 읽고 씁니다. UI가 없어도 동작합니다.
반환값 구조
모든 API 메서드는 최소한 다음 키를 포함하는 dict를 반환합니다:
{
"success": bool,
"message": str,
}실패 시 추가 키가 포함될 수 있습니다:
{
"success": False,
"message": str,
"error": str, # 에러 상세 내용
}예외 처리 규칙
잘못된 입력은 예외를 발생시키고, 작업 자체의 실패는 success: False로 반환합니다.
| 상황 | 동작 |
|---|---|
| 파일이 존재하지 않음 | FileNotFoundError 발생 |
| 잘못된 슬롯 번호 / 빈 슬롯 | ValueError 발생 |
| 잘못된 인수 타입 | TypeError 발생 |
| 라이센스 인증 실패 | 초기화 시 PermissionError 발생 |
| 작업 실패 (복구 가능) | {"success": False, ...} 반환 |