콘텐츠로 이동

원격 제어 매뉴얼 개요

이 문서는 hfVisualizer와 hfSectionVisualizer를 명령줄에서 원격으로 제어하려는 사용자를 위한 원격 제어 매뉴얼입니다.

다음과 같은 경우에 원격 제어 명령을 사용합니다.

  • 이미 실행 중인 뷰어 인스턴스를 제어할 때
  • 반복적인 GUI 작업을 자동화할 때
  • 재사용 가능한 명령 시퀀스를 스크립트로 저장할 때
  • 배치 작업에서 대화상자를 열지 않고 처리하고 싶을 때

1.1 빠른 시작

가장 빠르게 시작하려면 아래 순서를 따르면 됩니다.

  1. 프로그램을 일반 방식으로 실행합니다.
  2. list 또는 status를 실행합니다.
  3. open으로 파일을 열거나 현재 문서에 연결합니다.
  4. 필요에 따라 display, selection, preprocessing, postprocessing 명령을 실행합니다.
  5. save 또는 결과 export를 실행합니다.

1.1.1 프로그램을 일반 방식으로 실행

hfVisualizer.exe [file]
hfSectionVisualizer.exe [file]

1.1.2 실행 중인 인스턴스에 명령 보내기

hfVisualizer --remote [--target <id>] [--timeout-ms <ms>] <command> [args]
hfSectionVisualizer --remote [--target <id>] [--timeout-ms <ms>] <command> [args]
  • remote control 명령에서 <id>는 list 결과에 표시되는 대상 인스턴스 식별자입니다.
  • 가장 권장하는 형식은 list 첫 번째 칸에 나오는 전체 uuid입니다.
  • 고유한 uuid prefix나 server 전체 이름도 사용할 수 있지만, 여러 인스턴스가 동시에 실행 중일 때는 전체 uuid가 가장 분명하고 안전합니다.

1.1.3 가장 먼저 시도해 볼 명령

hfVisualizer --remote list
hfVisualizer --remote target set 60bae260-bf0a-4ad1-86ae-e9ef22bc8133
hfVisualizer --remote status
hfVisualizer --remote open D:\Work\model.inp
hfVisualizer --remote save

1.2 기본 사용 규칙

1.2.1 대상 창 선택

  • hfVisualizer --remote target set <id>는 이후의 hfVisualizer --remote ... 명령이 같은 실행 인스턴스를 계속 대상으로 삼도록 설정합니다.
  • hfSectionVisualizer --remote target set <id>는 이후의 hfSectionVisualizer --remote ... 명령이 같은 실행 인스턴스를 계속 대상으로 삼도록 설정합니다.
  • hfVisualizer --remote target show / target clear는 저장된 기본 대상을 확인하거나 지웁니다.
  • hfSectionVisualizer --remote target show / target clear도 동일하게 동작합니다.
  • --target <id>는 1회성 override가 필요할 때 사용합니다.
  • <id>는 list 결과에 표시되는 대상 인스턴스 식별자입니다.
  • 가장 권장하는 <id>는 list 첫 번째 칸에 나오는 전체 uuid입니다.
  • 고유한 uuid prefix나 list에 표시되는 server 전체 이름도 사용할 수 있습니다.
  • 여러 인스턴스가 동시에 실행 중일 때는 너무 짧은 prefix보다 전체 uuid 또는 충분히 긴 고유 prefix를 권장합니다.
  • hfVisualizer는 --target이 없고 저장된 기본 대상이 있으면 그 대상을 먼저 사용합니다.
  • hfSectionVisualizer도 동일한 우선순위를 따릅니다.
  • 저장된 기본 대상이 없고 실행 중 인스턴스가 정확히 1개면 자동 선택합니다.
  • 여러 인스턴스가 실행 중인데 --target과 기본 대상이 모두 없으면, 잘못된 창에 명령이 가지 않도록 실패합니다.
  • 저장된 기본 대상이 더 이상 존재하지 않으면 자동 추측하지 않고 실패하며, target clear 또는 target set을 다시 실행해야 합니다.
  • target set/show/clear는 두 프로그램 모두 로컬 클라이언트 명령이며, GUI 프로세스로 원격 제어 요청을 보내지 않습니다.
hfVisualizer --remote target set <id>
hfVisualizer --remote target show
hfVisualizer --remote target clear
hfSectionVisualizer --remote target set <id>
hfSectionVisualizer --remote target show
hfSectionVisualizer --remote target clear
  • target set <id>:
  • list에 표시되는 전체 uuid, 고유 uuid prefix, 또는 전체 server name으로 실행 중 인스턴스 하나를 찾습니다.
  • 이후 --target 없이 실행할 때 사용할 기본 대상으로 저장합니다.
  • target show:
  • 기본 대상이 저장되어 있는지 JSON으로 출력합니다.
  • 저장된 대상이 현재도 살아 있으면 resolved: true를 반환합니다.
  • 저장된 대상이 stale 상태면 resolved: false와 함께 오류 정보를 반환합니다.
  • target clear:
  • 저장된 기본 대상을 제거합니다.
  • 일반 hfVisualizer --remote ... 명령의 대상 결정 순서:
  • 명시적 --target <id>
  • target set으로 저장된 기본 대상
  • 실행 중 인스턴스가 정확히 1개인 경우 자동 선택
  • 그 외에는 추측하지 않고 실패
  • --target <id>는 target set 이후에도 항상 1회성 override로 사용할 수 있습니다.

예시:

hfVisualizer --remote list
hfVisualizer --remote target set 60bae260-bf0a-4ad1-86ae-e9ef22bc8133
hfVisualizer --remote target show
hfVisualizer --remote status
hfVisualizer --remote --target 864937a3-0922-4a0c-b377-9a2ec5c10d82 status
hfVisualizer --remote target clear

hfSectionVisualizer --remote list
hfSectionVisualizer --remote target set 4d2f7aa1-5f6d-4e23-9c62-6a63dc7f914b
hfSectionVisualizer --remote target show
hfSectionVisualizer --remote status
hfSectionVisualizer --remote --target 7f3f8f20-8a68-4d3c-bd8d-3e6c6d7f0b12 status
hfSectionVisualizer --remote target clear

1.2.2 파일 경로 처리

  • 절대 경로는 그대로 사용합니다.
  • 상대 경로는 최상위 CLI 작업 디렉터리를 기준으로 해석합니다.
  • 저장 경로가 필요한데 현재 문서가 한 번도 저장된 적이 없으면 SAVE_PATH_REQUIRED로 실패합니다.
  • remote CLI는 PowerShell이나 cmd.exe가 명령줄을 먼저 인자로 분해한 뒤의 값을 받습니다.
  • 큰따옴표 자체는 최종 값의 일부가 아니며, shell에서 하나의 인자를 묶는 역할만 합니다.
  • 하나의 인자에 공백이 없으면 큰따옴표가 있는 형태와 없는 형태는 보통 동일합니다. 이 규칙은 select node, select element, select surface, select edge 같은 명령에 똑같이 적용됩니다.
  • --content "..."처럼 인자 내부에 공백이 있거나 공백이 포함된 파일 경로를 전달할 때는 큰따옴표가 필요합니다. 꼭 필요하지 않아도 가독성을 위해 큰따옴표를 유지할 수 있습니다.

1.2.3 비대화형 동작

  • 원격 제어 명령은 자동화를 위해 설계되었으며 modal dialog를 열지 않습니다.
  • GUI에서는 사용자 입력을 요구하던 동작도, 원격 제어에서는 prompt를 띄우지 않고 실패합니다.

1.2.4 스크립트 사용

<app> --remote [--target <id>] [--timeout-ms <ms>] script <file>
<app> --remote [--target <id>] script-save [file]
  • 스크립트 파일은 한 줄에 하나의 command tail을 담습니다.
  • 스크립트 파일 안에 <app> --remote를 넣지 않습니다.
  • 스크립트 파일 안에 --target <id>를 넣지 않습니다. 대상 선택은 바깥 script 명령에서 해결합니다.
  • hfVisualizer, hfSectionVisualizer의 target set/show/clear는 로컬 클라이언트 명령이므로 스크립트 안에서는 사용할 수 없습니다.
  • 빈 줄과 # 주석 줄은 무시합니다.
  • 스크립트 안에서 다시 script를 중첩 호출하는 것은 허용되지 않습니다.
  • script는 fail-fast 방식으로 동작하여, 첫 번째 실패 줄에서 즉시 중단합니다.

1.2.5 세션 및 history 파일

  • 런타임 파일은 <sessionRoot>/.hyfeast/ 아래에 저장됩니다.
  • 기본 history/script 파일:
  • hfVisualizer: <sessionRoot>/.hyfeast/hfVisualizer.<uuid>.ipc.txt
  • hfVisualizer 기본 대상 파일: <sessionRoot>/.hyfeast/hfVisualizer.defaultTarget.json
  • hfSectionVisualizer: <sessionRoot>/.hyfeast/hfSectionVisualizer.<uuid>.ipc.txt
  • hfSectionVisualizer 기본 대상 파일: <sessionRoot>/.hyfeast/hfSectionVisualizer.defaultTarget.json
  • script-save는 script가 그대로 읽을 수 있는 형식으로 command tail을 기록합니다.

1.2.6 종료 코드

  • hfVisualizer와 hfSectionVisualizer는 같은 remote CLI 종료 코드 체계를 사용합니다.
  • 성공: 0
  • 잘못된 인수 또는 사용법 오류: 2
  • 대상 선택 실패: 3
  • 원격 제어 연결 실패: 4

  • 원격 제어 타임아웃: 5

  • 명령이 실패하면 CLI는 보통 ERROR[...] 형식의 문자열을 출력하고, 동시에 0이 아닌 종료 코드도 반환합니다.

  • 예를 들어 hfVisualizer --remote new가 SAVE_PATH_REQUIRED로 실패하면 콘솔에는 오류 문자열이 보이고, 종료 코드는 2입니다.

cmd.exe에서 종료 코드를 확인하는 방법:

hfVisualizer --remote new
echo %ERRORLEVEL%

PowerShell에서 종료 코드를 확인하는 방법:

hfVisualizer --remote new
$LASTEXITCODE

같은 방식으로 hfSectionVisualizer도 확인할 수 있습니다:

hfSectionVisualizer --remote status
echo %ERRORLEVEL%