fullseye

Fullseye Studio 완전 가이드

무거운 처리는 창을 멈추지 않고 실행됩니다. 아래 영역에는 현재 단계와 진행률이 표시되며, 중지 요청은 다음 단계 경계에서 확인됩니다. 실행 중 설정이 바뀌면 표시 결과의 세대를 밝히고, 이전 설정의 완료 결과를 보거나 현재 설정으로 다시 실행할 수 있습니다.

처리 목적을 검색하면 후보가 현재 입력에 적용 가능, 전처리 필요, 기타의 세 그룹으로 나뉩니다. 단계를 추가하지 않고 후보를 한 번 실행해 볼 수 있습니다. 실행에 실패하면 Problems 창에 원인, 위치, 다음 작업이 표시되며 입력 재선택, 나란히 비교, 상세 로그 열기, 매개변수 편집, 제안 단계 검색으로 이동할 수 있습니다.

日本語 · English · 简体中文 · 繁體中文 · 한국어 · Deutsch · हिन्दी

Fullseye Studio는 HDevelop풍의 시각적 파이프라인 워크벤치입니다. 연산자를 검색해 배치하고, 2개의 다이얼을 슬라이더로 돌리고, 중간 결과를 확대/축소·패닝하며 한 단계씩 실행하고, 완성된 파이프라인을 --ops 문자열 / Python / JSON으로 내보낼 수 있습니다. 실체는 fullseye API의 얇은 GUI 프런트엔드이며, 파이프라인 로직(PipelineModel)·Inspector(inspect_result)·샘플 모음(recipes)은 모두 Qt에 의존하지 않고 개별적으로 단위 테스트되어 있습니다.

이 가이드는 studio.py(build_window)를 실제 코드와 대조해 기능을 나열한 것입니다. UX/디자인 의도는 STUDIO_UX.md에, v14 지각 패널의 배경은 V14.md / PERCEPTION.md에 있습니다.


실행 방법

GUI extras(PySide6)가 필요합니다(pip install -e ".[gui]").

py -3.11 studio.py          # 저장소 루트에서 직접
fullseye-studio             # pip install -e .가 되어 있다면 콘솔 스크립트로

실행하면 1320×860 크기의 메인 창이 열립니다(제목: Fullseye Studio). assets/fullseye.ico가 있으면 창/작업 표시줄 아이콘으로 붙습니다. 초기 상태에서는 합성 데모 이미지(demo_image, 에지·블롭·그라디언트를 포함한 256×256)가 로드되어 있습니다.


화면 구성 (3개 패널)

상단에는 메뉴 바(File / Edit / View / Run / Help)와 브랜드 툴바, 하단에는 상태 표시줄(마우스를 올렸을 때의 좌표+픽셀 값, flash()의 일시적 메시지)이 있습니다. 중앙은 좌우로 나뉜 3개 패널입니다.

패널 구획(QGroupBox) 역할
왼쪽 SAMPLE PIPELINES / OPERATORS 샘플 로드와 연산자 브라우저
가운데 PIPELINE / SELECTED STAGE · KNOBS / EXPORT & I/O 파이프라인 구성·다이얼 조정·내보내기
오른쪽 IMAGE / DISPLAY & PERCEPTION (v14) / ANALYSIS 결과 표시·컬러맵/지각·히스토그램/Inspector

초기 분할 폭은 340 / 360 / 640 px이며, 오른쪽 패널이 신축합니다.


왼쪽 패널: Operators 브라우저

샘플 파이프라인(SAMPLE PIPELINES)

드롭다운에서 25개의 기성 레시피(recipes.py) 중 하나를 선택하면, 파이프라인이 그 레시피로 교체됩니다. 예: “Edge — Sobel + Otsu”, “Denoise — bilateral + unsharp”, “Segment — blob / coin”, “Count — blobs”, “Texture — Gabor” 등. 우선 실행해 보며 내용을 파악하는 출발점으로 편리합니다.

연산자 브라우저(OPERATORS)

삽입 위치는 “선택된 단계의 바로 다음”입니다. 단계를 선택하지 않았다면 맨 끝에 추가됩니다.


가운데 패널: 파이프라인 구성과 단계 실행

PIPELINE(단계 목록)

각 행은 N. op (a=…, b=…) -> 결과 요약 형식이며, 그 단계까지 실행한 결과 상태(image/region/feature 등)가 오른쪽에 표시됩니다.

단계를 선택하면 그 단계까지의 중간 결과가 오른쪽 IMAGE 패널에 그려지고, 아래의 ANALYSIS(히스토그램 / Inspector)도 함께 갱신됩니다. 이는 “단계별 디버거”에 해당합니다.

SELECTED STAGE · KNOBS(다이얼 조정)

선택한 단계의 상세 정보(op_detail: 이름·in → out sort·카테고리·HALCON 별칭)를 표시하고, 2개의 슬라이더 a / b(0.00~1.00)로 조정합니다. 값을 움직이면 즉시 결과가 재계산됩니다. 단계를 선택하지 않았을 때는 슬라이더가 비활성화됩니다(의미 없는 다이얼을 죽은 상태로 두지 않는 설계).

다이얼의 의미는 연산자마다 다릅니다(반경 / 임계값 / σ / 방향 등). 무엇을 조정하는지는 단계 상세 레이블과 툴팁으로 확인할 수 있습니다.

EXPORT & I/O


오른쪽 패널: 표시·지각·분석

IMAGE(결과 뷰)

DISPLAY & PERCEPTION (v14)

ANALYSIS


Command palette(Ctrl+P)

Ctrl+P를 누르면 이름으로 어떤 동작이나 어떤 연산자든 실행할 수 있는 퍼지 검색 대화상자가 열립니다. 접두 일치 > 단어 접두 일치 > 부분 일치 순으로 순위가 매겨집니다(palette_filter, Qt에 의존하지 않고 단위 테스트됨). 동작(예: ▸ Open image)이 먼저 나오고, 이어서 모든 연산자(예: op: gaussian)가 나열되며, Enter로 실행합니다. 키보드만으로 연산자 삽입까지 완결할 수 있습니다.


키보드 단축키

앱 내에서는 Help ▸ Keyboard shortcuts(F1)로 전체 목록이 표로 표시됩니다(자체 문서화). 주요 항목(studio.py의 act_* 정의 기준):

동작 단축키 동작 단축키
Open image Ctrl+O Remove stage Del
Synthetic demo Ctrl+D Move stage up / down Ctrl+↑ / Ctrl+↓
Save result Ctrl+S Clear pipeline Ctrl+Shift+Backspace
Open pipeline Ctrl+Shift+O Zoom in / out Ctrl+= / Ctrl+-
Save pipeline Ctrl+Shift+S Fit / Actual size (1:1) Ctrl+0 / Ctrl+1
Export Ctrl+E 3D surface Ctrl+3
Quit Ctrl+Q Reset to start Home
Command palette Ctrl+P Step forward Ctrl+→
Keyboard shortcuts F1 Run all Ctrl+Enter
Image Viewer Ctrl+Shift+I Run a ledger op Ctrl+Shift+L
Pipeline as code → editor Ctrl+Shift+E    

각 동작은 메뉴·툴바·버튼 중 어느 것에서 호출하든 동일한 핸들러가 실행됩니다(하나의 동작, 여러 개의 입구).


HDevelop dev_* 렌더링 제어 지시문

HDevelop과 마찬가지로, 프로그램에서 렌더링 동작을 제어할 수 있습니다. Program 창의 스크립트에 dev_* 행을 쓰면, 이미지 단계가 아니라 표시 지시문으로 해석되어 Apply 시 적용됩니다(docs/HDEVELOP_DEV_OPS.md에 전체 43개 dev_*가 망라되어 있습니다).

지시문 효과 대응 UI
dev_update_window ('off'|'on') 그래픽 창의 자동 갱신 전환 View ▸ Display updates ▸ Graphics window
dev_update_var ('off'|'on') 변수 창의 자동 갱신 전환 위와 동일, Variable window
dev_update_pc ('off'|'on') 실행 커서 갱신 전환 위와 동일, Program counter
dev_update_time ('off'|'on') 행별 처리 시간 표시 전환 위와 동일, Operator timings
dev_update_off () / dev_update_on () 위 항목 전체를 일괄 off / on 툴바 Auto-update 토글
dev_set_part (Row1, Col1, Row2, Col2) 표시 범위(확대/이동) 설정·음수=전체 마우스 휠/Fit과 병용
dev_set_lut ('gray'|'jet'|'viridis'…) 컬러맵(LUT) 전환 View ▸ Display mode
dev_clear_window () 현재 창을 지움 —
set_system ('thread_num', N) OpenCV 작업 스레드 수 설정(0=기본/전체) Tools ▸ System settings
set_system ('operator_timeout', ms) 소프트 연산자 타임아웃(느린 단계를 Run status에서 경고) 위와 동일
dev_set_draw ('fill'|'margin') region 오버레이의 채우기(fill)/윤곽(margin) 전환 View ▸ Display mode = region overlay
dev_set_color ('red'|'green'…) region 오버레이 색상 위와 동일
dev_set_line_width (N) margin 윤곽선 두께(px) 위와 동일
dev_disp_text ('label', Row, Col) 결과 위에 텍스트 주석 추가(다음 렌더링/dev_clear_window에서 사라짐) —
dev_open_window (Row, Col, W, H) 그래픽 창을 열어서 배치하고 현재 창으로 지정(다시 Apply해도 같은 창을 재배치=증식하지 않음) Ctrl+G / Window ▸ Graphics
dev_set_window (Handle) 핸들로 현재 창 전환 창 클릭
dev_set_window_extents (Row, Col, W, H) 현재 창의 위치·크기(-1=현재 상태 유지) 창 드래그
dev_close_window () 현재 창을 닫음(상주하는 메인 창은 보호됨) 창의 ×
set_system ('max_graphics_windows', N) 창 개수 상한(기본 256·모든 경로 fail-closed) Tools ▸ System settings ▸ Windows

용도: 맨 앞에 dev_update_off ()를 두면 렌더링 비용 없이 무거운 처리나 대량 편집을 할 수 있고, dev_update_on ()으로 현재 상태까지 한 번에 갱신할 수 있습니다(HDevelop의 성능 기법과 동일). 갱신이 꺼져 있는 동안에는 상태 표시줄 오른쪽에 updates off: …가 표시되므로, 정지된 상태가 “고장난 것처럼” 보이는 일은 없습니다. 툴바의 Auto-update 토글로도 동일하게 전환할 수 있습니다.

주의(정직한 고지): dev_*는 파이프라인 단계와 달리 if/for를 따르지 않고 무조건 적용됩니다 (분기 안에 두어도 실행됩니다). 최상위 레벨에 작성하세요. 지원되지 않는 dev_*는 오류가 됩니다.

직접 실행해 보기: File ▸ dev_* visualization demo를 실행하면, coins 이미지 + 위의 dev_*를 실제로 사용하는 HDevelop 프로그램(분할→영역을 청록색 윤곽선 + 레이블로 표시)이 로드되어 적용됩니다. 연습용 샘플 이미지는 File ▸ Sample images(16장, 출처는 studio_assets/sample_images/manifest.json 참조. 합성 이미지 = 자체 제작물/coins·camera 등 = skimage.data의 BSD/퍼블릭 도메인 소재. tools/gen_sample_images.py로 재생성 가능)에 있습니다. 그중 5장은 외관 검사(FA)용 장면으로, 사진이 아니라 조명·반사 물리 계산(illumdesign)과 PoC의 촬상 모델로 만든 것입니다: 헤어라인 금속의 흠집, 수지의 찍힘과 이물 섬유, 각인된 로트 번호, 백라이트로 본 구멍 뚫린 플레이트, 용접 X선 영상의 기공. 각각 결함의 정답 마스크 (<이름>.truth.png)와 manifest의 설명이 있고, “FA — …” 레시피 하나와 짝을 이루며(그 레시피가 결함을 찾는다는 것을 테스트로 확인), tools/gen_fa_samples.py로 재생성합니다.


다국어 지원(en / ja / zh, 표 기반)

UI 언어는 Tools ▸ Language / 言語 / 语言에서 전환할 수 있습니다(선택이 기억됩니다). 번역문은 studio_assets/i18n.json에 일원화된 표로 관리되며, 코드 변경 없이 언어를 추가할 수 있습니다:

연산자 도움말은 op_help/<name>.<lang>.html이 있으면 언어별로 표시됩니다. 정직한 고지: 실행 중 변화하는 상태 문구(running… / PASS 등)와 연산자 노트 본문은 현재 번역 대상이 아닙니다(연산자 노트의 영어화는 docstring 이중 언어화와 세트인 향후 과제입니다).

Python 편집기와 IDE 기능(2026-08-30)

Studio는 “파이프라인에서만 코드를 호출할 수 있는” 단계를 넘어, Python 개발 환경으로도 사용할 수 있습니다.

드래그 앤 드롭으로 열 수 있는 것(2026-10-03)

파일이나 폴더를 메인 창에 끌어다 놓으면 종류에 맞는 창이 열립니다(여러 개를 한꺼번에 놓으면 여러 창). 전체 목록은 Help ▸ 열 수 있는 파일(드래그 앤 드롭)… 에 있습니다. 그 표는 Studio가 실제로 쓰는 확장자 상수에서 만들어지므로 이 절보다 새로울 수 있습니다.

놓는 것 여는 곳 비고
이미지(png / jpg / tif / webp / pgm / pfm / jp2 …), 폴더 이미지 뷰어 목록, 확대, 픽셀 값, 히스토그램, ‘파이프라인 입력으로 사용’. 폴더는 바로 안의 이미지
.py Python 편집기(파일마다 탭 하나)  
.json 파이프라인  
점군과 메시(PLY / STL / PCD / OBJ / OFF / XYZ) 3-D 뷰어 ASCII와 바이너리 모두(PLY는 리틀·빅 엔디언, PCD는 binary_compressed도)
3DGS(.ply / .splat) 3-D 뷰어 색은 구면 조화 DC 항, 불투명도 0.05 미만은 숨김
의료 볼륨(NIfTI / NRRD / MHA / DICOM) 3-D 뷰어 SimpleITK 등이 필요
glTF(.glb / .gltf), LiDAR(.las / .laz) 3-D 뷰어 pygltflib / laspy 필요
로봇(MJCF / URDF) 3-D 뷰어 .xml은 루트가 <mujoco> 또는 <robot>일 때만. mujoco 필요
모션 캡처(.bvh), 뉴런 형태(.swc) 3-D 뷰어 BVH 관절 궤적을 시간으로 색칠
동영상, 애니메이션 GIF, HDF5 비디오 큐브  
이벤트 카메라 (x, y, t, p)(txt / csv / npy / npz) 비디오 큐브 내용으로 판별해 극성 프레임으로
.npy 형태로 분류 2-D → 입력 이미지, (N, 3 / 6) → 점군, 3-D → 볼륨
Markdown, SVG 문서 뷰어  
오디오(wav / mp3 / flac / ogg …) 오디오 창 파형, 스펙트로그램, 재생. WAV 이외는 soundfile
로봇 모델 + qpos .npy (T, nq) 를 함께 로봇 재생 슬라이더와 재생 버튼

대장 op를 눌러 시험하기(Tools ▸ 대장 op 실행…, Ctrl+Shift+L)(2026-10-03)

형식 대장의 op(PIV·수학·운전·3-D 등 약 1,700개)를 인수의 형식에 맞는 입력란으로 실행하는 창입니다. 왼쪽 검색란에 이름이나 단어를 넣고 op를 고르면 오른쪽에 인수 양식이 나타납니다.

샘플로 실행되지 않는 op도 있습니다(op별 샘플을 만드는 방식의 한계로, 2026-10-03 실측에서는 60개 중 27개가 샘플 그대로 실행됨). 창이 실패를 늘리지 않는다는 것은 “샘플을 op에 직접 넘긴 결과와 일치한다”는 게이트로 확인합니다.

CSV 열을 테이블 연산에 할당

형식 입력이 table이면 기존 원장 실행기에서 CSV 파일…을 선택한다. 각 역할은 실제 열에서만 고른다. 게이지 R&R은 part / 부품 ID, operator / 측정자, value / 측정값을 사용한다. 검사는 행 수, 고유 키, 결측값과 반복 수를 보여 준다. 반복 수가 다른 그룹은 이름과 함께 실행 전에 거부하고 자동 보정하지 않는다. 할당은 연산과 헤더 서명별로 저장되어 같은 형식에서만 재사용된다. CSV는 수정하거나 이름을 바꾸지 않는다.

결과 뷰의 표시 방법

결과 표시 방법
flow2d (2, h, w) 색상 = 방향, 밝기 = 속도인 색상환 그림 위에 화살표 그림(가장 긴 화살표 = 간격의 0.9배)
1차원 수열 꺾은선(MATLAB의 plot(y))
표(dict) 길이가 같은 수치 열을 겹쳐 꺾은선으로. t / x / freq … 열이 있으면 가로축으로
(h, w, 4) / (h, w, 1) / 복소수 흰 바탕에 합성한 RGB / 회색조 / 절댓값 |z|
빈 배열·4차원 이상 모양과 값 범위를 글로(첫 값을 “스칼라”로 보이지 않음)

결과 캐시, 확인 필요 표시, 입력 이미지 참조(2026-10-19)

폴더에 같은 처리를 적용

Run ▸ 이 처리를 폴더에 적용… 에서 입력 폴더와 파일 패턴을 고르고, 첫 장·가운데 장·마지막 장 또는 임의의 한 장으로 결과를 확인한 뒤 전체를 실행할 수 있습니다. 실행을 시작할 때 입력과 처리 열을 한 번만 고정하므로, 도중에 노브를 바꿔도 진행 중인 배치의 조건은 바뀌지 않습니다.

같은 이름의 파일은 “덮어쓰지 않음” “덮어씀” “일련번호 붙임” 중에서 고르고, 하위 폴더를 대상으로 하면 출력 쪽에도 같은 계층을 만듭니다. summary.csv 에는 파일 이름, 상태, 처리 시간, 숫자 출력, 오류 이유가 들어갑니다. 한 장의 읽기나 처리가 실패해도 나머지는 계속 진행하며, 끝난 뒤 실패한 파일과 이유를 목록으로 확인할 수 있습니다. 정지 요청은 현재 한 장이 끝나는 경계에서 받아들여지고, 실제로 멈출 때까지 “정지됨”을 표시하지 않습니다.

작업 모드와 패널

위쪽 막대에서 처리 구성, 결과 비교, 수치 조사, 코드 만들기를 선택하면 해당 작업에 필요한 패널이 커지고 나머지는 접힙니다. Ctrl+1~4로도 전환할 수 있습니다. 입력, 처리 단계, 계산된 결과는 바뀌지 않으며 모드별로 직접 조정한 패널 배치도 기억됩니다. F11은 잠시 이미지만 크게 표시하고 Esc는 직전 배치를 정확히 복원합니다. “패널 찾기…”에서는 일본어나 영어 이름으로 숨은 패널을 다시 표시할 수 있습니다.

표시 범위와 원본 데이터

이미지마다 자동은 이미지별로 범위를 계산하고, 비교 이미지에서 공통은 A/B 전체에 한 범위를 사용하며, 수동은 값 범위를 사용하는 표시 모드에 입력한 하한과 상한을 적용합니다. region overlay처럼 범위를 사용하지 않는 모드는 라벨에 그 사실을 표시합니다. “표시 처리만 적용”이라는 안내처럼 원본 값은 바뀌지 않습니다. NaN과 Inf는 자홍색으로, 범위 밖 값은 끝 색으로 표시하고 픽셀 수를 경고합니다. 저장할 때는 원본 수치, 현재 표시 이미지, 둘 다 중에서 고르며 기본값은 원본 수치입니다.

Export와 Save/Open의 관계

Studio에서 구성한 파이프라인은 3가지 형태로 가지고 나갈 수 있습니다.

형식 내보내는 방법 사용처
--ops 문자열 Export(Ctrl+E) CLI의 imgevolve.py pipeline --ops "…" / run "…"에 붙여넣기
Python 함수 Export(Ctrl+E) 자신의 코드에 fullseye.run_pipeline(...)로 내장
JSON Save pipeline(Ctrl+Shift+S) FullseyeEngine.load(...) / imgevolve.py run pipeline.json으로 실행

설계는 Studio에서, 실행은 코드/CLI에서라는 HDevelop→HDevEngine에 해당하는 흐름은 JSON을 매개로 이루어집니다. JSON을 받아 실행하는 쪽은 ENGINE.md를 참조하세요.


관련 문서