콘텐츠로 이동

시츄에이션 (Situations)

시츄에이션(Situation)은 명명된 파일 저장 시나리오입니다. 다음을 정의합니다:

  • 파일이 저장될 위치 (매크로 템플릿 사용)
  • 해당 위치에 파일이 이미 존재할 때 처리하는 방식 (충돌 정책 사용)
  • 저장에 실패할 경우 수행할 작업 (선택적 폴백 시츄에이션 사용)

노드가 파일을 저장해야 할 때 현재 속한 시츄에이션(예: save_node_output)을 지정하면, 프로젝트 시스템이 해당 시츄에이션의 매크로를 사용하여 경로를 해석하고 정책을 적용합니다.

충돌 정책 (Collision policies)

정책 동작
create_new 충돌하지 않는 파일 이름을 찾을 때까지 파일 이름의 카운터를 증가시킵니다. 매크로에는 {_index?:NN}(선택 사항 — 첫 저장 시 생략, 충돌 시 인덱스 부여) 또는 {_index:NN}(필수 — 첫 저장부터 인덱스 부여)을 포함할 수 있습니다. 둘 다 없으면 시스템은 충돌 시 해석된 파일 이름 뒤에 _1, _2, …를 추가합니다.
overwrite 확인을 묻지 않고 기존 파일을 덮어씁니다.
fail 파일이 이미 존재하는 경우 작업을 중단하고 오류를 보고합니다.

create_dirs 필드는 중간 상위 디렉터리를 자동으로 생성할지(true, mkdir -p와 유사) 아니면 상위 디렉터리가 없을 때 오류를 발생시킬지(false)를 제어합니다.

폴백 (Fallbacks)

시츄에이션은 폴백(대체) 시츄에이션을 지정할 수 있습니다. 기본 시츄에이션이 매크로를 해석할 수 없는 경우(예: 필수 변수 누락 등) 시스템은 폴백을 시도합니다. 기본 save_file 시츄에이션은 대부분의 다른 시츄에이션에서 사용하는 최소한의 폴백입니다.

기본 시츄에이션

save_file

macro:  {file_name_base}{_index?:03}.{file_extension}
policy: create_new, create_dirs: true

프로젝트 루트(또는 호출자의 경로 컨텍스트가 지정한 위치)에서의 일반적인 파일 저장입니다. 대부분의 다른 시츄에이션에 대한 폴백 역할을 합니다. {_index?:03} 변수는 0으로 패딩된 선택적 변수로, 첫 저장 시에는 생략되고 충돌 시 001, 002, …로 진행됩니다(시퀀스 전체에 걸쳐 패딩 너비 유지).

copy_external_file

macro:    {inputs}/{node_name?:_}{parameter_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

사용자가 외부 파일을 프로젝트로 복사하거나 드래그하여 가져올 때 사용됩니다. 파일은 inputs 디렉터리에 배치됩니다. 파일의 출처를 식별하기 위해 노드 이름과 파라미터 이름이 선택적 접두사로 앞에 추가됩니다.

예시:

node_name="LoadImage", parameter_name="source", file_name_base="photo", file_extension="jpg"
→ inputs/LoadImage_source_photo.jpg

node_name 제공 안됨, file_name_base="photo", file_extension="jpg"
→ inputs/photo.jpg

download_url

macro:    {inputs}/{sanitized_url}
policy:   overwrite, create_dirs: true
fallback: save_file

노드가 URL에서 파일을 다운로드할 때 사용됩니다. URL은 안전한 파일 이름으로 정리(sanitize)됩니다. 동일한 URL에서 다운로드된 파일은 복제되지 않고 덮어쓰기됩니다.

save_node_output

macro:    {outputs}/{sub_dirs?:/}{node_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

노드가 출력을 생성하고 저장할 때 사용됩니다. 파일은 outputs 디렉터리에 저장됩니다. 선택적 하위 디렉터리({sub_dirs?:/})를 사용하여 outputs 내부를 중첩 구성할 수 있습니다. 노드 이름은 선택적 접두사입니다.

예시:

outputs="outputs", node_name="ImageGen", file_name_base="render", _index=1, file_extension="png"
→ outputs/ImageGen_render001.png

sub_dirs="lighting/pass_a", node_name="ImageGen", file_name_base="render", file_extension="exr"
→ outputs/lighting/pass_a/ImageGen_render.exr

save_output_directory

macro:  {outputs}/{sub_dirs?:/}{dir_name}_v{###}
policy: create_new, create_dirs: true

노드가 출력을 단일 파일이 아니라 폴더에 쓸 때 사용됩니다. 실행할 때마다 번호가 매겨진 새 폴더가 만들어지므로 이전 결과가 덮어쓰이지 않습니다. 번호는 디스크에 있는 가장 큰 버전 번호부터 이어서 올라가며, 빈 번호는 채워집니다.

예시:

dir_name="renders"
→ outputs/renders_v001      (첫 번째 실행)
→ outputs/renders_v002      (두 번째 실행)

save_file_sequence

macro:  {outputs}/{file_extension_directory?:/}{sub_dirs?:/}{file_name_base}_v{###}/{file_name_base}.####.{file_extension}
policy: create_new, create_dirs: true

노드가 프레임(예: 비디오에서 추출한 프레임)처럼 번호가 매겨진 일련의 파일을 쓸 때 사용됩니다. 실행할 때마다 자체 버전 폴더가 생기며, 그 안의 프레임은 별도로 번호가 매겨집니다.

# 표시 두 가지는 역할이 다릅니다. 중괄호 안의 {###}은 폴더의 버전 번호입니다. 중괄호 밖의 단독 ####는 각 프레임의 번호가 들어가는 자리입니다. 매크로에는 {###}을 하나만 사용할 수 있으므로 프레임 번호에는 단독 형식을 사용하세요. 프레임 번호에 대한 자세한 내용은 시퀀스를 참조하세요.

예시:

file_name_base="frames", file_extension="png"
→ outputs/images/frames_v001/frames.0001.png
→ outputs/images/frames_v001/frames.0002.png
→ outputs/images/frames_v002/frames.0001.png   (두 번째 실행)

두 시츄에이션 모두 현재 프로젝트 템플릿에 포함되어 있습니다. 레거시 템플릿으로 만든 프로젝트에는 포함되지 않으며, 이 경우 노드는 같은 레이아웃을 만드는 내장 매크로를 사용합니다.

save_preview

macro:    {previews}/{drive_volume_mount?:/}{source_relative_path?:/}{source_file_name}.{preview_format}
policy:   overwrite, create_dirs: true
fallback: save_file

미리보기 썸네일을 생성할 때 사용됩니다. 미리보기는 각 소스 파일이 정확히 하나의 미리보기를 갖도록 소스 파일의 디렉터리 계층 구조를 미러링합니다. 미리보기는 버전 관리되지 않고 덮어씁니다. previews 디렉터리의 기본값은 .griptape-nodes-previews(숨김 폴더)입니다.

save_static_file

macro:    {workflow_dir?:/}{static_files_dir}/{file_name_base}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

정적 파일 관리자가 정적 에셋을 저장할 때 사용됩니다. 파일은 현재 워크플로 디렉터리의 static_files_dir 하위 디렉터리에 저장됩니다. 재생성 시 기존 파일을 덮어씁니다.

save_temp_file

macro:    {temp}/{node_name?:_}{file_name_base}{_index?:03}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

노드가 처리 중에 중간 파일이나 임시 스크래치 파일을 작성해야 할 때 사용됩니다(예: 색 공간 변환 단계 사이에 기록되는 임시 EXR). 파일은 temp 디렉터리에 저장되며 사용 후 노드에서 삭제해야 합니다.

save_workflow

macro:    {workspace_dir}/{sub_dirs?:/}{file_name_base}.{file_extension}
policy:   overwrite, create_dirs: true
fallback: save_file

워크플로 파일이 기록될 때마다 사용됩니다. 저장할 때뿐 아니라, 에디터가 워크플로 파일을 만들 때(워크플로를 분기하거나 템플릿에서 복사할 때)도 사용됩니다. 이 경우에도 이 시츄에이션을 거치므로, save_workflow의 위치를 바꾸면 명시적 저장뿐 아니라 이 모든 경우에 영향을 줍니다.

워크플로 파일은 선택적 {sub_dirs?:/} 접두사를 통해 하위 디렉터리 계층 구조를 유지하면서 워크스페이스 루트에 저장됩니다. 워크플로를 저장하면 버전을 새로 생성하지 않고 기존 파일을 덮어씁니다. 번호가 매겨진 시퀀스로 저장하려면 아래의 create_versioned_workflow를 참조하세요.

예시:

workspace_dir="/projects/demo", file_name_base="my_workflow", file_extension="py"
→ /projects/demo/my_workflow.py

sub_dirs="archived", file_name_base="my_workflow", file_extension="py"
→ /projects/demo/archived/my_workflow.py

create_versioned_workflow

macro:    {workspace_dir}/{sub_dirs?:/}{file_name_base}_v{_index:03}.{file_extension}
policy:   create_new, create_dirs: true
fallback: save_file

버전 관리 저장 의도로 워크플로가 저장될 때 사용됩니다. 저장할 때마다 시퀀스에서 다음 패딩 인덱스를 가진 새 파일(my_workflow_v001.py, my_workflow_v002.py, …)이 생성되므로 사용자는 이전 작업을 덮어쓰지 않고 스냅샷을 유지할 수 있습니다.

버전 증가는 매크로 기반으로 실행됩니다. 버전 지정 저장이 실행되면 엔진은 이전 저장 경로를 이 시츄에이션의 매크로와 역방향 매칭하여 바인딩된 패딩 슬롯을 포함하여 매크로가 정의한 모든 변수를 추출합니다. 다음 저장은 해당 변수를 그대로 재사용하며, 충돌 탐색을 통해 기존 파일을 지나 패딩 인덱스를 증가시킵니다. 버전 접미사에 대해 하드코딩된 것이 없으므로 매크로 커스터마이징(예: _v{_index:03}을 .{_index:04}로 변경)도 정상 작동합니다. 새로운 패턴이 순방향 저장과 역방향 매칭 모두에 대한 규약이 됩니다.

팁: 커스텀 프로젝트에서는 자동 인덱스 슬롯을 더 명시적인 _v{###} 구문으로 전환할 수 있습니다(시퀀스 슬롯 ({###}) 참조). 기본 3자리 숫자의 경우 {_index:03}과 동일하게 동작하며, 999를 넘어갈 때 0 패딩을 유지하는 대신 자연스럽게 4자리 이상으로 확장됩니다.

이 시츄에이션은 SaveWorkflowRequest에 create_versioned=True를 전달하여 API 레이어에서 선택되며, UI에서는 별도의 메뉴 항목(예: "Save New Version")으로 제공됩니다. 자동 인덱스 규약에 대해서는 매크로 — 숫자 패딩을 참조하세요.

참고: save_workflow를 수정하여 create_versioned_workflow + 플래그 대신 create_new를 직접 사용하면 저장 시 경고가 발생합니다. 해당 구성도 작동하여 첫 번째 저장은 _v001에 저장되지만, 이후의 모든 저장은 제자리 덮어쓰기 분기를 타서 _v002로 증가하는 대신 _v001에 다시 기록됩니다. 진정한 버전 관리를 위해서는 create_versioned_workflow를 사용하세요.

예시:

workspace_dir="/projects/demo", file_name_base="my_workflow", file_extension="py"
  첫 번째 저장 → /projects/demo/my_workflow_v001.py
  두 번째 저장 → /projects/demo/my_workflow_v002.py
  세 번째 저장 → /projects/demo/my_workflow_v003.py

노드가 시츄에이션을 사용하는 방식

노드의 시츄에이션은 사용자가 아닌 노드 작성자가 선택합니다. 파일을 저장하는 노드는 ProjectFileParameter를 사용하며, 해당 파라미터가 빌드될 때 시츄에이션 이름이 내장됩니다. 노드 전면에는 시츄에이션 필드가 표시되지 않습니다. 노드에는 파일 이름 파라미터(주로 Output File이라고 함)가 표시되고, 시츄에이션은 그 뒤에서 작동합니다.

파일 이름 파라미터가 바로 ProjectFileParameter입니다. 여기에 입력하는 모든 내용은 file_name_base 및 file_extension 변수가 되며, 시츄에이션의 매크로가 파일이 실제로 저장될 위치를 결정합니다. 따라서 save_node_output을 사용하는 노드에 render.png를 입력하면 프로젝트 루트의 render.png가 아니라 outputs/MyNode_render.png가 생성됩니다. 노드는 파일 이름 요소를 제공하고, 프로젝트 시스템은 나머지 모든 것(디렉터리 경로, 내장 변수)을 제공합니다.

거의 모든 생성 및 저장 노드는 save_node_output을 사용합니다. 다른 시츄에이션들은 해당 이름이 가리키는 시스템 부분에서 사용됩니다. 파일을 드래그하여 가져오면 copy_external_file, URL 다운로드는 download_url, 썸네일은 save_preview, 워크플로 저장은 save_workflow를 사용합니다.

노드 출력을 완전히 다른 위치로 보내기 (Sending one node's output somewhere else entirely)

render.png처럼 단순한 이름만 입력하면 대상 위치는 시츄에이션이 결정합니다. 대부분의 경우 이것이 원하는 동작입니다. 노드 하나에 대해 이를 바꾸는 방법은 두 가지가 더 있습니다:

  • 상대 폴더 경로 — lighting/pass_a/render.png처럼 입력하면 파일이 시츄에이션의 디렉터리 안에 중첩됩니다. 예를 들어 save_node_output은 파일을 outputs/lighting/pass_a/에 저장합니다. 시작 위치는 여전히 시츄에이션이 정합니다.
  • 절대 경로 — /mnt/studio/renders/render.png, C:\renders\render.png, 또는 두 경로의 file:///mnt/studio/renders/render.png 형식입니다. 이 경우 정확한 디스크 위치를 직접 지정하는 것이므로 시츄에이션이 경로를 만들지 않으며, 파일은 지정한 곳에 저장됩니다. outputs 디렉터리도, 노드 이름 접두사도, 버전 번호도 추가되지 않습니다. 해당 위치에 이미 파일이 있을 때의 처리는 여전히 시츄에이션이 정합니다. save_node_output에서는 이전 렌더를 잃지 않도록 render_1.png로 저장됩니다. 경로에 아직 없는 폴더가 있으면 시츄에이션이 이를 만듭니다.

웹 주소는 대상 위치가 될 수 없습니다. 노드는 https://example.com/render.png에 저장할 수 없으며, 이를 입력하면 예상하지 못한 위치에 파일을 만드는 대신 오류가 발생합니다.

절대 경로는 프로젝트 시스템을 건너뛰므로 프로젝트 시스템이 제공하는 기능도 적용되지 않습니다. 경로가 해당 컴퓨터에 특화되어 있으므로, 이러한 경로가 포함된 워크플로는 다른 사람의 컴퓨터에서 해당 위치를 찾지 못합니다. 해당 머신에 없는 드라이브를 가리키는 경로(macOS나 Linux에서 여는 C: 경로 등)는 예상하지 못한 위치에 C:라는 폴더를 만드는 대신 오류를 발생시킵니다. 모든 노드가 새 위치에 쓰도록 하려면 프로젝트 파일에서 시츄에이션을 직접 편집하세요.

노드가 사용하는 시츄에이션 확인하기

노드의 파일 이름 파라미터 위에 마우스를 올립니다. 툴팁에 시츄에이션 이름이 표시됩니다. 예:

Output filename (uses 'save_node_output' situation template)

모든 노드와 해당 시츄에이션을 나열하는 별도의 패널이 없으므로, 툴팁이 특정 노드를 확인하는 신뢰할 수 있는 방법입니다. 커스텀 노드의 소스 코드에서는 ProjectFileParameter에 전달되는 situation= 인수입니다.

단일 노드에서 시츄에이션 오버라이드하기

프로젝트 파일을 편집하지 않고 단일 노드가 쓰는 위치를 변경하려면 노드의 파일 이름 파라미터에 있는 톱니바퀴(cog) 버튼을 클릭하세요. 그러면 노드의 시츄에이션과 현재 파일 이름이 미리 채워진 File Output Settings 노드가 생성되어 해당 파라미터에 연결됩니다.

File Output Settings 노드는 시츄에이션이 숨겨두었던 항목을 노출하며 각 필드를 변경할 수 있습니다:

  • Situation: 프로젝트 파일의 커스텀 시츄에이션을 포함한 모든 시츄에이션을 선택할 수 있습니다. 변경하면 아래의 매크로와 충돌 정책이 다시 로드됩니다.
  • Macro: 이 연결에 대해 편집 가능한 경로 템플릿입니다.
  • If File Exists: 충돌 정책(Increment Version, Overwrite Existing 또는 Abort / Error)을 지정합니다.
  • Auto Create Path: 누락된 상위 디렉터리를 자동 생성할지 여부를 설정합니다.

여기서 설정한 모든 내용은 연결된 해당 노드에만 적용됩니다. 모든 노드가 쓰는 위치를 변경하려면 프로젝트 파일에서 시츄에이션을 직접 편집하세요.

커스텀 시츄에이션 추가하기

예시는 커스터마이징 가이드를 참조하세요.

프로젝트 파일에서 save_node_output과 같은 기본 시츄에이션을 재정의하면 노드를 편집할 필요 없이 해당 시츄에이션을 사용하는 모든 노드의 대상 위치가 변경됩니다. 새로운 시츄에이션을 추가하는 것은 이를 선택하는 대상이 있을 때만 적용됩니다. 즉, situation=을 전달하는 커스텀 노드이거나 이를 가리키는 File Output Settings 노드가 있어야 합니다.