YK MBD Image Workbench 사용설명서

Auto_Optiresolve 1.3.0 사용 설명서

Windows 10(1809 이상)/11 64비트 · 원본 OptiResolve 엔진 전용

이 문서는 배포본의 docs/사용설명서.html(F1 도움말)과 같은 내용을 더 자세히 풀어 쓴 설명서입니다. 화면 사진 대신 각 영역과 버튼을 글로 설명합니다. 실제 화면 사진은 docs/screenshots/와 F1 도움말에 있습니다(v1.1~v1.2 화면이며 v1.3에서 배치는 바뀌지 않았습니다).

1. 이 프로그램은 무엇인가요

Auto_Optiresolve는 384-well plate 현미경 이미지에 기존 OptiResolve 엔진을 실행하고, 처리 전후를 같은 위치에서 비교한 뒤, 필요한 well만 Images 폴더의 이미지를 결과로 바꾸는 프로그램입니다.

• 계산은 해시로 고정된 원본 OptiResolve 배포본과 별도의 Python 3.11.3이 합니다. 이 프로그램은 알고리즘을 바꾸지 않습니다. 결과 JPEG는 원본 OptiResolve의 결과와 같습니다(v1.0~v1.2 검증 기록: docs/검증결과.md).
• 이 프로그램이 추가하는 것은 실행·검토·반영 절차입니다: 채널 자동 인식, 결과 재사용, 저신호 well 알림, 전후 동기 비교, 원본 백업, 반영 저널과 복구, 원본 복원.
• OptiResolve Modified(개선 엔진)는 계획 문서만 있고 실행 모드는 없습니다.

다른 도구와의 관계

• Auto_Optiresolve는 혼자 동작합니다. 현미경 촬영과 deconvolution 처리로 만들어진 plate_*/채널/images/Images/*.jpg를 바로 읽으며, 다른 도구의 결과가 필요하지 않습니다.
• 작업대의 다른 세 도구(384cropper, ScalebarGUI, 이미지 그리드 합치기)는 별개의 프로그램입니다. 정해진 순서가 없으니 필요한 도구만 골라 쓰거나 이 프로그램만 써도 됩니다.
• 런처(YK MBD Image Workbench)는 이 프로그램을 여는 방법 중 하나일 뿐입니다. Auto_Optiresolve.exe를 직접 실행해도 똑같이 동작합니다.

정량 분석 주의: 원본 OptiResolve는 이미지마다 대비를 넓히고 JPG로 저장합니다. 결과 픽셀값을 곧바로 형광량으로 비교하지 마세요.

2. 설치와 실행

1. 배포 압축(Auto_Optiresolve_v1.3.0_Windows_x64.zip)을 원하는 위치에 풉니다.
2. 폴더 안의 Auto_Optiresolve.exe를 실행합니다. Python 설치나 인터넷 연결은 필요 없습니다.
3. 다음 폴더와 파일은 지우거나 옮기지 마세요: engine(원본 OptiResolve), runtime311(계산용 Python 3.11.3), _internal(화면 프로그램), docs(설명서), worker.py, engine-manifest.json.

엔진 파일이 하나라도 바뀌면 계산 단계에서 “Engine bundle verification failed” 또는 “Unsupported OptiResolve executable”로 실행을 거부합니다. 이때는 온전한 배포본을 다시 풀어 사용하세요.

EXE에 폴더 경로를 인수로 주면(예: 바로가기 대상 뒤에 폴더 경로 추가) 시작할 때 그 폴더를 바로 불러옵니다.

3. 입력 폴더 구조와 인식 규칙

샘플/                      ← 샘플 루트 (plate_* 폴더를 가진 폴더)
  plate_1/
    SpGr_500ms/            ← 채널 폴더
      scaninfo.txt         ← (선택) Filter : SpGreen
      data/                ← 처리·수정하지 않음
      images/              ← 상위 images의 파일은 처리하지 않음
        Images/            ← 처리 대상 (두 번째 Images 폴더)
          1_1.jpg          ← A1
          7_9.jpg          ← G9

• 샘플 루트 찾기: 선택하거나 끌어놓은 폴더 아래에서 plate_로 시작하는 하위 폴더를 가진 폴더를 샘플로 찾습니다. 여러 샘플이 들어 있는 상위 폴더를 골라도 되고, plate·채널·Images 폴더를 골라도 최대 4단계 위까지 올라가 샘플 루트를 찾습니다. data, OptiResult, Pre-Opti, .auto_opti, .git, __pycache__ 폴더와 바로가기(심볼릭 링크)는 탐색하지 않습니다.
• 처리 대상 파일: 채널 폴더의 images/Images(대소문자 무관) 안의 파일입니다.
• well 좌표: 파일 이름이 행_열 숫자여야 합니다. 행 1~16(A~P), 열 1~24. A1=1_1, C4=3_4, G9=7_9, P24=16_24.
• 자동 교체 지원 형식: JPEG(.jpg, .jpeg). PNG·TIFF·BMP는 목록에 문제로 표시되고 처리하지 않습니다. 다른 형식을 확장자만 바꿔 쓰지 마세요.
• 채널 자동 인식: 채널 폴더 이름의 첫 단어(_, 공백, - 앞)와 scaninfo.txt의 Filter : 값을 봅니다.

폴더 이름과 scaninfo.txt가 다르거나, 모르는 Filter 값이 있거나, 둘 다 없으면 채널이 “선택 필요”로 표시됩니다. 화면 위쪽 채널 목록에서 직접 고르면 그 선택이 작업 기록에 저장되어 다음에도 유지됩니다.

채널 문제 표시 (왼쪽 정보 영역에 표시)

파일 문제(좌표·형식·중복)가 있는 채널은 분석을 시작할 수 없습니다. 탐색기에서 문제 파일을 채널 폴더 밖으로 옮긴 뒤 대기열 우클릭 → 샘플 다시 읽기를 하세요.

4. 화면 구성

창 제목은 Auto_Optiresolve 1.3.0입니다. 위에서 아래, 왼쪽에서 오른쪽 순서로 설명합니다.

4.1 머리글

• Auto_Optiresolve 제목과 ● ORIGINAL ENGINE 표시: 원본 엔진만 사용함을 나타냅니다.
• 사용 설명서 F1: 배포본의 docs/사용설명서.html을 엽니다.
• 작업 로그: 이번 실행 중의 진행 메시지와 오류 전문(traceback)을 시간과 함께 보여 줍니다. 프로그램을 닫으면 사라지므로 필요하면 내용을 복사해 두세요.

4.2 작업 단계 버튼 줄

4.3 왼쪽: 샘플 대기열과 상태

• 샘플 대기열 · N개: 샘플 이름 아래에 plate / 채널 · N wells 항목이 있습니다. 체크 상자가 분석 대상입니다. BF는 회색이며 체크해도 곧바로 해제됩니다. 항목을 클릭하면 그 채널이 가운데에 표시되고, 샘플 이름을 클릭하면 그 샘플의 첫 형광 채널이 표시됩니다. 우클릭 메뉴는 8장에서 설명합니다.
• 채널 상태 카드: 현재 채널의 전체 well 수, 분석 결과 있음, 파일 교체 완료, 원본 사용, 확인 필요, 반영 대기, 처리 실패 장수.
• 선택 well 상태(노란 왼쪽 선): 한 well을 선택하면 분석 결과·현재 파일·예약·실행 대기를, 여러 well을 선택하면 개수 요약을 표시합니다.
• 정보 영역: 샘플 이름, 채널·배율, 기존 결과 수, 원본 연결 필요 수, 미완료 반영 건수, 채널 문제 목록.
• 처리 전 원본 폴더 연결: 7.3절.
• 미완료 반영 작업 복구: 7.5절.
• 검토 결과 CSV 내보내기: 불러온 모든 샘플의 모든 채널 기록을 CSV로 저장합니다(10장).
• 저신호 검사 설정: 6장.
• 현재 샘플 목록에서 닫기: 대기열에서만 뺍니다. 파일은 지우지 않습니다.

4.4 가운데 위: 채널 설정과 384-well 지도

• 채널 제목 plate / 채널 · N wells, 채널 목록(선택 필요/SpGreen/SpRed/GFP/DAPI/BF), 배율 목록(4X/10X/20X/40X, 기본 4X). 바꾸면 곧바로 작업 기록에 저장됩니다. 채널을 형광 채널로 바꾸면 저신호 검사를 다시 합니다.
• 384-well 지도 ▾: 지도와 미리보기 영역을 접거나 펼칩니다. 접으면 비교 화면이 넓어집니다.
• 표시: A1 ↔ 1_1: 지도·목록·이미지의 well 이름을 문자형(G9)과 파일명형(7_9) 사이에서 바꿉니다.
• well 이동 입력칸: G9 또는 7_9를 입력하고 Enter 또는 이동 → 그 well을 선택하고 확대합니다.
• ◀ 검토 / 검토 ▶: “검토 필요” 상태인 well을 차례로 찾아갑니다.
• 현재 화면 N wells · A1: 왼쪽 비교 화면에 보이는 well 수. 지도에서는 굵은 글씨로 표시됩니다.
• 지도: 촬영한 well만 활성화되고 나머지는 ·입니다. 색은 현재 파일 상태입니다: 청색 = 원본 사용, 녹색 = 교체 완료, 적색 = 확인 필요. 노란 칸 = 선택. 칸을 클릭·Ctrl+클릭·Shift+클릭으로 선택하고, 행(A~P)·열(1~24) 머리글을 클릭하면 한 줄 전체를 선택합니다. 칸에 마우스를 올리면 파일명과 상태가 나옵니다.

4.5 지도 오른쪽: 교체 후 미리보기

원본과 결과가 섞인 plate 전체 모습을 보여 줍니다. 파일은 바꾸지 않습니다.

테두리 색: 파랑 = DECON(처리 전 원본), 초록 = OPTI(OptiResolve 결과), 분홍 = 확인 필요(결과 교체 불가, 원본 연결 필요, 외부 변경 등). 노란 안쪽 점선 = 현재 선택. 휠로 확대, 드래그로 이동, 클릭으로 well 선택. 미리보기는 저장된 밝기 그대로이며 아래 보기 밝기의 영향을 받지 않습니다.

4.6 가운데: 전후 비교

• 도구 줄: 플레이트 전체(Ctrl+0), 선택 well 확대, 100%(Ctrl+1), 좌우 위치 동기화(기본 켜짐), 보기 밝기 0.25×~4.00× 슬라이더와 초기화. 밝기는 화면에만 적용되며 파일은 바뀌지 않습니다. 객관적인 비교는 1.00×에서 하세요.
• 왼쪽 처리 전 · Deconvolution 원본: 반영 후에도 Pre-Opti의 원본을 보여 줍니다. 원본이 없으면 “원본 연결 필요”.
• 오른쪽 OptiResolve 결과 미리보기: OptiResult의 결과. 없으면 “결과 없음”. 파일 교체 여부는 아래 목록과 지도에서 확인합니다.
• 휠 = 확대/축소, 드래그 = 이동, 클릭 = 선택, 더블클릭 = 그 well 확대. 멀리서는 축소 이미지, 가까이서는 원본 해상도를 읽습니다. 파일을 읽지 못하면 “읽기 실패”가 표시됩니다.

4.7 아래: 선택·예약 버튼과 well 목록

• 전체 선택, 모두 선택 해제(선택만 지웁니다. 예약·파일은 그대로).
• 선택 → 교체 예약: 선택 well을 “결과로 교체” 예약. 결과가 없거나 처리 실패인 well은 예약되지 않고, 상태 표시줄에 실제 변경 개수와 제외 개수가 따로 나옵니다.
• 선택 → 원본 유지 예약: 선택 well을 “원본 유지” 예약(이미 교체된 well은 다음 반영 때 원본으로 돌아갑니다).
• 선택을 다른 채널로 복사: 같은 plate의 다른 형광 채널 하나를 골라, 같은 좌표 well에 선택 well의 예약(교체/유지/검토)을 복사합니다. 교체·유지가 복사된 well은 검토 완료로 표시됩니다. 대상 채널에 결과가 없거나 처리 실패인 well에는 교체 예약이 복사되지 않습니다.
• 원본 복원: 7.4절.
• 의심 well만: 저신호로 표시된 well만 목록에 보여 줍니다.
• 선택 N개 · 이름들: 현재 선택. 선택된 well은 지도·이미지의 노란 테두리, 목록의 ✓로도 표시됩니다.
• well 목록 열:

4.8 맨 아래: 상태 표시줄

진행 메시지, 작업 경과 시간(분:초), 진행 막대. 분석 중에는 완료 · 재사용 · 실패 / 전체 개수가 표시됩니다.

5. 단계별 사용법

5.1 샘플 추가

1. 1 샘플 추가를 누르고 샘플 루트(또는 여러 샘플의 상위 폴더)를 고릅니다. 여러 폴더를 창에 끌어놓아도 됩니다.
2. 불러오는 동안 각 형광 채널의 원본 확인과 저신호 검사를 합니다(“원본 / 저신호 확인 · 채널”). 이때 샘플 폴더에 .auto_opti/project.json(작업 기록)이 만들어집니다. 이미지 파일은 바뀌지 않습니다.
3. 구조를 찾지 못하면 “plate_*/채널/images/Images 구조를 찾지 못했습니다”가 나옵니다. 3장의 구조를 확인하세요.

5.2 채널·배율 확인

1. 대기열에서 채널을 하나씩 눌러 채널과 배율이 맞는지 확인합니다. 기본 배율은 4X(NA 0.13)입니다. 10X=NA 0.30, 20X=0.50, 40X=0.75, 픽셀 크기는 4.5 µm로 고정입니다.
2. 처리하지 않을 채널은 체크를 해제합니다. BF는 항상 제외됩니다.
3. 정보 영역에 문제 문구가 있으면 3장의 표대로 해결합니다.

5.3 분석 시작

1. 2 분석 시작을 누릅니다. 체크한 형광 채널이 순서대로 처리됩니다.
2. 이미 같은 입력·엔진·설정(파장, NA, 배율, 픽셀 크기, JPEG 품질 95)으로 만든 결과가 있으면 다시 계산하지 않고 재사용합니다. 다시 계산하려면 기존 결과 재계산을 체크합니다.
3. 결과는 먼저 .auto_opti/runs/<실행 ID>/results에 만들어지고, 해시 검증 후 Images/OptiResult/<파일명>.jpg로 복사됩니다. Images의 이미지는 바뀌지 않습니다.
4. 이미 교체한 채널은 Pre-Opti의 원본으로 다시 분석합니다.
5. 중간에 멈추려면 작업 중지. 현재 이미지가 끝난 뒤 멈추며, 다음 실행 때 끝난 결과는 재사용됩니다.
6. 한 장이 실패하면(예: 손상된 JPEG) 그 well만 “처리 실패”로 표시하고 나머지는 계속합니다. 실패 well은 “검토 필요”가 되고 교체할 수 없습니다.
7. 분석이 끝나면 저신호 검사를 다시 합니다. 사용자가 아직 정하지 않은 well은 저신호가 아니면 “결과로 교체” 예약, 저신호면 “검토 필요 · 원본 유지”가 됩니다.

5.4 전후 비교

1. 3 전후 비교를 누르거나 채널을 선택합니다.
2. 휠·드래그로 확대·이동하면 좌우가 같은 위치로 움직입니다(좌우 위치 동기화).
3. well 이동칸에 G9를 입력하고 Enter → G9가 선택되고 확대됩니다. Alt+방향키로 이웃 well로 이동합니다.
4. ◀ 검토 / 검토 ▶ 또는 의심 well만으로 저신호 well을 빠르게 찾습니다.
5. 지도 오른쪽 미리보기의 예약 반영 후 · 예상으로 반영 후 plate 모습을 미리 봅니다.

5.5 결정: 결과 적용 / 원본 유지

1. 지도·목록·이미지에서 well을 선택합니다(Ctrl+클릭 개별, Shift+클릭 범위, 머리글 클릭 행/열 전체, 전체 선택).
2. 선택 → 교체 예약(결과 적용) 또는 선택 → 원본 유지 예약을 누릅니다. 상태 표시줄에 “N개 well 예약 변경 · 아직 파일은 교체하지 않았습니다.”가 나옵니다.
3. 예: 초록 채널에서 G9 결과가 배경 잡음만 강조했다면 G9를 선택하고 원본 유지 예약, 나머지는 교체 예약. 빨강 채널의 판단은 따로 합니다. 같은 판단을 쓰려면 선택을 다른 채널로 복사.
4. 선택 해제는 예약 취소가 아닙니다. 예약을 바꾸려면 다시 선택해서 다른 예약 버튼을 누르세요.

5.6 파일 교체 실행

1. well을 선택하고 4 파일 교체 실행을 누릅니다.
2. 확인 창의 반영 범위를 고릅니다: 현재 채널 전체 또는 현재 선택 well만(선택이 있으면 기본값). 창에 결과 적용·원본 유지·검토 필요·처리 실패 장수와 실제 변경 예정 장수가 나옵니다. 검토 필요 항목은 원본을 유지합니다.
3. 반영을 누르면:
4. 채널 전체의 현재 파일과 원본 해시를 먼저 확인합니다. 하나라도 맞지 않으면 아무 파일도 바꾸지 않고 멈춥니다.
5. 채널의 원본 전체를 Pre-Opti에 복사·검증합니다(처음 한 번만. 이미 있으면 같은지만 확인).
6. 반영 저널(.auto_opti/transactions/<ID>.json)을 만들고 파일을 하나씩 바꿉니다. 결과·원본 모두 재인코딩 없이 바이트 그대로 복사합니다.
7. 끝나면 “N장 반영 완료 · 원본은 Pre-Opti에 보존됨”. 지도 색이 녹색(교체 완료)으로 바뀝니다.

5.7 원본 복원

1. 복원할 well을 선택하거나(선택 없이 채널 전체도 가능) 원본 복원을 누릅니다(대기열 우클릭 → 현재 채널 원본 복원…도 같음).
2. 범위를 고르고 원본 복원. 선택 범위의 Images 파일이 Pre-Opti의 원본으로 돌아가고 예약은 “원본 유지 · 검토 완료”가 됩니다.
3. 결과(OptiResult)는 비교를 위해 남아 있습니다. 나중에 다시 교체할 수 있습니다.

5.8 미완료 반영 작업 복구

반영·복원 중 프로그램이 꺼지거나(정전, 강제 종료) 오류가 나면 저널이 “미완료”로 남습니다. 이때는 새 반영·분석이 “미완료 반영 작업이 있습니다. 먼저 작업 복구를 실행하세요.”로 거부됩니다.

1. 해당 샘플의 채널을 선택하고 미완료 반영 작업 복구를 누릅니다.
2. 프로그램이 저널에 적힌 남은 파일을 끝까지 반영합니다(되돌리지 않고 원래 하려던 작업을 완료). 이미 바뀐 파일은 건너뜁니다.
3. 저널에 적힌 전/후 어느 쪽과도 다른 파일(외부 프로그램이 바꾼 파일)이 있으면 “복구 대상 파일이 외부에서 변경되었습니다”로 멈춥니다. 그 파일을 확인한 뒤 다시 시도하세요.
4. 복구 후 원래 상태로 되돌리고 싶으면 원본 복원을 사용합니다.

6. 저신호 검사(검토 알림)

신호가 약한 well(예: sample loss)에서 원본 엔진이 배경 잡음만 크게 늘리는 경우를 찾도록 돕는 알림입니다. 진단이 아니며, 계산과 저장 이미지에는 영향을 주지 않습니다.

• 원본(또는 Pre-Opti)을 550×550으로 줄여 채널 색(SpRed=R, SpGreen·GFP=G, DAPI=B)의 가운데 원(반지름 220 px) 안에서 중앙값, MAD, 대비(99백분위 − 중앙값)를 잽니다.
• 저신호: 대비 ≤ max(최소 대비 기준, MAD 배수 × 1.4826 × MAD). well이 5개 이상이면 추가로 대비 ≤ 채널 중앙 대비 비율 × 채널 대비 중앙값일 때만 저신호입니다.
• 저신호 검사 설정 창의 기본값(단일 출처 auto_opti/model.py):

• 설정은 샘플마다 저장되며, 바꾸면 그 샘플의 모든 형광 채널을 다시 검사합니다. 사용자가 이미 정한 예약(검토 완료)은 유지됩니다.
• 검사 후 사용자가 정하지 않은 well의 예약: 처리 실패 → 검토 필요, 저신호 → 검토 필요(원본 유지), 그 밖에 결과가 있으면 → 결과로 교체, 결과가 없으면 → 원본 유지.

주의 — 이미 있던 외부 결과: 이 프로그램 밖에서 만든 OptiResult 결과가 있는 샘플을 불러오면, 사용자가 아직 정하지 않았고 저신호가 아닌 well은 불러오는 순간 “결과로 교체” 예약(교체 대기)이 됩니다(분석 결과 열: “외부 결과 있음”). 이 상태에서 현재 채널 전체로 파일 교체를 실행하면 외부 결과가 Images에 반영됩니다. 외부 결과가 있는 샘플은 반영 전에 목록의 “분석 결과”와 “실행 대기” 열을 꼭 확인하세요. (이 동작은 v1.2와 같게 유지했으며, 변경 여부는 검토 중인 제안입니다.)

7. 파일과 폴더

7.1 채널 폴더 안

Images/
  7_9.jpg          ← 후속 분석이 읽는 활성 이미지 (교체 대상)
  OptiResult/
    7_9.jpg        ← OptiResolve 결과 (항상 .jpg, 파일명은 원본과 같은 이름)
  Pre-Opti/
    7_9.jpg        ← 최초 처리 전 원본. 한 번 만든 뒤 절대 덮어쓰지 않음

7.2 샘플 루트의 .auto_opti (작업 기록)

기록은 모두 샘플 루트 기준 상대 경로라서 샘플 폴더 전체를 옮겨도 계속 사용할 수 있습니다. 옮길 때 Images, OptiResult, Pre-Opti, .auto_opti를 함께 옮기세요. 기존 _combineimage.jpg 같은 다른 파일은 수정하지 않습니다.

7.3 처리 전 원본 폴더 연결

Images에 이미 처리된 이미지만 있고 원본이 없으면(“원본 연결 필요”) 비교·재분석·반영을 할 수 없습니다.

1. 채널을 선택하고 처리 전 원본 폴더 연결을 누릅니다.
2. 처리 전 원본 JPEG들이 같은 파일명으로 들어 있는 폴더를 고릅니다. 현재 Images 폴더나 OptiResult 폴더는 고를 수 없습니다.
3. 채널의 모든 well 원본이 있어야 하며, 기록된 원본·백업과 다르면 거부합니다. 통과하면 Pre-Opti로 복사·검증하고 저신호 검사를 다시 합니다. Images 파일은 바꾸지 않습니다.

8. 대기열 우클릭 메뉴와 폴더 열기

샘플 또는 채널 위에서 우클릭합니다. 작업 중에는 열리지 않습니다.

9. 단축키와 마우스

10. CSV 내보내기

기본 파일명 OptiResolve_review.csv(UTF-8 BOM, Excel에서 한글이 깨지지 않음). 열:

sample, plate, channel, well, filename, decision(apply/keep/review), reviewed, applied, weak_signal, contrast, source_hash, result_hash, error

11. 안전 규칙 (원본 보존)

1. 최초 원본 보존: 첫 반영 전에 채널 원본 전체를 Pre-Opti에 복사하고 SHA-256으로 확인합니다. 이미 있는 백업은 덮어쓰지 않으며, 다르면 작업을 멈춥니다.
2. 검증 후 변경: 반영 전 채널 전체의 현재 파일·원본·결과 해시를 확인합니다. 기록과 다른 파일(외부 변경)이 하나라도 있으면 아무것도 바꾸지 않습니다.
3. 재인코딩 없음: 결과와 원본을 바이트 그대로 복사합니다. 복사 후 해시를 다시 확인하고 원자적으로 교체합니다.
4. 반영 저널: 모든 교체는 저널에 먼저 기록되고 파일마다 완료 표시를 남깁니다. 중단되면 “미완료 반영 작업 복구”로 끝까지 완료합니다.
5. 여유 공간 확인: 복사 전 필요한 공간 + 16 MiB 여유가 없으면 시작하지 않습니다.
6. 샘플 잠금: 한 샘플에서는 한 번에 한 작업만 합니다. 다른 작업이 쓰는 중이면 “다른 작업이 이 샘플을 사용하고 있습니다.” 프로그램이 비정상 종료해도 잠금은 운영체제가 풉니다.
7. 경로 제한: 샘플 폴더 밖의 파일은 읽거나 쓰지 않습니다.
8. 분석은 Images를 바꾸지 않음: 분석은 OptiResult와 .auto_opti에만 씁니다.
9. 종료 보호: 작업 중에는 창을 닫을 수 없습니다(“작업 진행 중”). 반영·복원 중에는 끝날 때까지 기다리세요.

12. 오류 메시지와 해결

v1.3부터 CSV 저장, 예약 저장, 채널·배율 저장, 선택 복사, 저신호 기준 저장, 작업 중지가 실패하면 오류 창이 나타나고, 작업(분석·반영·복원·복구·불러오기)이 실패하면 작업 확인 창에 원인이 표시됩니다. 미완료 반영 작업이 실제로 남아 있을 때만 복구 안내가 붙습니다. 오류 전문은 작업 로그에 있습니다.

13. 자주 묻는 질문

Q. 분석이 끝났는데 Images 폴더의 이미지가 그대로예요. 정상입니다. 분석은 OptiResult만 만듭니다. 검토 후 파일 교체 실행을 해야 Images가 바뀝니다.

Q. 선택을 해제했는데 예약이 그대로예요. 선택은 “지금 조작할 well”일 뿐입니다. 예약은 교체 예약/원본 유지 예약 버튼으로만 바뀝니다.

Q. 교체 예약을 눌렀는데 일부 well이 안 바뀌었어요. 결과가 없거나 처리 실패인 well은 교체 예약할 수 없습니다. 상태 표시줄에 제외된 개수가 나옵니다. 재분석 후 다시 예약하세요.

Q. 모든 파일을 처음 상태로 되돌리고 싶어요. 채널마다 원본 복원 → 범위 현재 채널 전체. Pre-Opti의 최초 원본으로 돌아갑니다.

Q. Pre-Opti나 .auto_opti를 지워도 되나요? 안 됩니다. 원본 복원·재분석·복구에 필요합니다. 샘플을 옮길 때도 함께 옮기세요.

Q. 결과를 다시 계산하고 싶어요. 기존 결과 재계산을 체크하고 분석을 시작합니다. 이전 결과는 .auto_opti/history에 보존됩니다. 배율을 바꾼 경우에는 체크하지 않아도 다시 계산합니다.

Q. 다른 컴퓨터로 옮겨도 되나요? 샘플 폴더 전체를 옮기면 됩니다. 기록은 상대 경로입니다.

Q. BF(명시야)는 왜 처리하지 않나요? 원본 엔진은 밝은 형광 신호를 가정합니다. BF는 기본 제외이며 체크할 수 없습니다.

Q. 이미 다른 방법으로 만든 OptiResult가 있는 샘플이에요. 불러오면 “외부 결과 있음”으로 표시되고, 저신호가 아닌 미검토 well은 교체 대기 상태가 됩니다(6장 주의). 반영 전에 목록을 확인하거나, 이 프로그램으로 기존 결과 재계산을 해서 원본 엔진 결과로 다시 만드세요. Images에 이미 처리된 이미지만 있으면 먼저 처리 전 원본 폴더 연결을 하세요.

Q. 분석이 오래 걸려요. 원본 엔진은 CPU와 정사각형 FFT를 사용합니다. 큰 이미지는 시간이 걸립니다. 작업 중지는 현재 이미지가 끝난 뒤 반영됩니다. 중지 요청 후에도 계산 프로그램이 300초 안에 끝나지 않는 비정상 상황에서는 프로그램이 강제로 종료합니다(v1.3).

Q. 작업 로그를 저장하고 싶어요. 작업 로그 창의 내용을 선택해 복사하세요. 계산 프로그램의 오류 출력은 .auto_opti/runs/<실행 ID>/worker.stderr.log에 파일로 남습니다.

Q. 여러 샘플을 한 번에 처리할 수 있나요? 여러 샘플을 불러오고 채널을 체크한 뒤 분석 시작을 누르면 순서대로 처리합니다. 파일 교체·복원은 현재 선택한 채널 단위로 합니다.

14. v1.3.0에서 바뀐 점

화면 배치·작업 순서·단축키·계산 결과는 v1.2와 같습니다. 오류 창 표시, 실제 예약 개수 표시, 실패한 실행의 기록(failed), 멈추지 않는 계산 프로그램의 강제 종료 등 안정성 개선입니다. 자세한 내용은 docs/v1.3-변경사항.md를 보세요.

384cropper 2.3.0 사용설명서

384cropper는 96/384 Well Plate 스캔 이미지에서 샘플별 Well 범위(crop)를 지정하고, RGB 보정을 적용해 여러 결과 이미지를 한 번에 저장하는 Windows 프로그램입니다. 같은 창에서 R/G/B 채널 합성(RGB merge)과, 이미지·분석값·ATP 측정값을 Well 위치로 묶은 통합 결과 엑셀도 만들 수 있습니다.

이 설명서는 2.2.1의 사용안내.md와 오프라인 HTML 설명서를 2.3.0 동작에 맞춰 통합·보완한 것입니다. 프로그램 안에서 F1 또는 도움말 버튼을 누르면 같은 내용의 HTML 설명서(사용설명서.html)가 열립니다. 인터넷 연결은 필요 없습니다.

목차

1. 프로그램의 목적
2. 설치와 실행
3. 화면 구성
4. 기본 작업 순서 (빠른 시작)
5. 이미지 가져오기
6. 영역(crop) 만들기와 편집
7. 미리보기: 확대·비교·출력 검증
8. RGB 보정
9. 결과 이미지 저장
10. 프로젝트(작업 파일) 저장과 열기
11. RGB 채널 Merge
12. 이미지·분석·ATP 통합 결과 엑셀
13. 명령줄 실행 옵션
14. 파일 이름과 저장 위치 정리
15. 설정 항목의 의미
16. 안전 규칙 (원본 보존)
17. 자주 나오는 오류와 해결
18. 자주 묻는 질문 (FAQ)
19. 단축키
20. 지원 범위와 한계
21. 2.3.0에서 달라진 점

1. 프로그램의 목적

무엇을 하나요?

• 스캐너가 만든 Plate 전체 이미지(보통 AnalysisResult/_combineimage.bmp, 최대 약 1억 5천만 화소)를 불러옵니다.
• 이미지를 96 Well(A1–H12) 또는 384 Well(A1–P24) 격자로 나누고, 샘플마다 Well 범위(예: B3-F8)를 지정합니다.
• 형광 이미지를 보기 좋게 RGB 레벨·밝기·대비·강도로 보정합니다.
• 샘플별 crop 이미지를 원본 형식 또는 PNG로 저장하고, 각 파일에 Well 정보(샘플명·태그·Well 범위·보정값)를 기록합니다.
• 필요하면 여러 원본의 채널을 합친 RGB merge 이미지와, 분석 결과·ATP를 합친 통합 엑셀을 만듭니다.

다른 도구와의 관계

• 384cropper는 혼자 동작합니다. 스캐너/분석 프로그램이 AnalysisResult 폴더에 만든 _combineimage 이미지와 분석 표(CSV/XLSX)를 바로 읽으며, 다른 도구의 결과가 필요하지 않습니다.
• 작업대의 다른 세 도구(Auto OptiResolve, ScalebarGUI, 이미지 그리드 합치기)는 별개의 프로그램입니다. 정해진 순서가 없으니 필요한 도구만 골라 쓰거나 이 프로그램만 써도 됩니다.
• 작업대 실행기(YK MBD Image Workbench 런처)는 384cropper를 여는 방법 중 하나일 뿐입니다. 384cropper 카드의 열기로 앱을 열거나, ATP 결과 통합 Excel로 결과 엑셀 창을 바로 띄울 수 있습니다(13장 --open-result). 프로그램을 직접 실행해도 똑같이 동작합니다.

384cropper는 원본 파일을 절대 수정하지 않습니다. 모든 결과는 새 파일로 저장하며 같은 이름이 있으면 번호를 붙입니다.

2. 설치와 실행

실행 파일(권장)

• 384cropper_YK_2.3.0.exe를 원하는 폴더에 두고 일반 권한으로 실행합니다(관리자 권한 실행은 권장하지 않습니다. 탐색기 드롭·연결 드라이브가 보이지 않을 수 있습니다).
• Python 설치가 필요 없습니다. 이전 버전 EXE와 나란히 두고 사용할 수 있습니다.
• 첫 실행 시 창은 최대화되어 열리고, 이후에는 마지막 창 위치·패널 폭을 기억합니다(15장 참고).

소스로 실행(개발/검증용)

README.md의 안내대로 Python 3.12와 requirements.txt의 패키지를 준비한 뒤 다음을 실행합니다.

python 384cropper_GUI_YK.py

3. 화면 구성

창은 위에서 아래로 상단 막대 → 상황 막대 → 작업 영역(왼쪽·가운데·오른쪽) → 저장 막대 → 상태줄로 구성됩니다.

3.1 상단 막대

창 제목에는 384cropper 2.3.0 | 작업 이름이 표시되고, 저장하지 않은 변경이 있으면 끝에 *가 붙습니다.

3.2 상황 막대

• 왼쪽: 이미지 N장 · 영역 N개(프로젝트에 연결되지 않은 이미지가 있으면 미연결 N장).
• 오른쪽: 미리보기 / 영역 / 보정 전환 탭(창이 좁을 때 보이는 패널 선택), 집중 보기 · F11 버튼.
• 창이 아주 좁으면 작업·화면 메뉴로 바뀌고, 집중 보기에서는 결과 저장 메뉴가 나타납니다.

3.3 왼쪽: 01 이미지 · 영역

• 제목 오른쪽의 Plate 선택(384 / 96) Well: 현재 이미지의 Plate 종류.
• 선택 N행 · 저장 N개 · 미연결 N장: 목록에서 고른 행 수와 실제로 저장될 crop 수.
• 경로 표시 방식: 폴더 6단계(기본, 상위 폴더 6개를 생략 없이) / 전체 경로 / 간단히(구별에 필요한 부분만).
• 전체 경로 보기: 선택한 이미지의 전체 경로를 큰 창에서 보고 복사.
• 목록 표: 열은 이미지 이름 (경로), 샘플명, crop 위치, 태그. 이미지 행 아래에 01 crop, 02 crop… 영역 행이 있고 영역 색 표시가 붙습니다. 행 위에 마우스를 잠시 두면 전체 경로가 뜹니다.
• 상세 편집: 경로 표시(클릭하면 전체 원본 경로 복사), 샘플명·crop 위치·태그 입력 칸, 영역 색 8색 팔레트와 …(직접 고르기).
• 버튼: ＋ 연속 추가, 복제, 영역 작업 메뉴(다른 이미지에 영역 복사…, 선택 영역에 태그 일괄 적용…, 선택 삭제, 저장 선택 해제, 이 이미지의 전체 Plate 영역 제거, 오른쪽/아래/왼쪽/위에 복제), 적용.
• 아래 안내문: 입력 예시와 오류 이유(예: 범위를 벗어난 Well).

3.4 가운데: 미리보기

• 전체 / 선택 crop: 이미지 전체 또는 현재 영역만 보기.
• 빠른 보기 · 근사 / 출력 검증: 7장 참고.
• 원본(보정 전 보기), A/B 비교(원본·보정을 경계선으로 나눠 보기), 화면 격자(Well 경계선), 원본 다시 읽기.
• 캔버스: 위·왼쪽 눈금에 열 번호(1–24)와 행 문자(A–P). 영역은 색 테두리와 번호·샘플명으로 표시, 선택 영역은 굵은 테두리와 모서리 손잡이.
• 아래: 배율 선택(화면 맞춤, 10–400%)과 − / +, 커서 위치의 Well · 원본 (x, y) px, 영역 모드 연속 추가 / 수정 / 이동과 안내, 현재 배율과 화면 품질(근사/원본 상세/출력 검증).

3.5 오른쪽: 이미지 보정

• 적용 범위 안내(현재 이미지 이름과 crop 수).
• 이지 / 심화 · RGB 모드 전환.
• 형광 프리셋 약 · 중 · 강, 보정 강도 (%) 칸과 슬라이더.
• LUT 진단 문구(밝기 순서 역전·단계 손실 확인).
• 심화 모드: 채널 RGB / R / G / B, 원본 히스토그램(로그 높이), 검정점 / 중간톤 · 감마 / 흰점.
• 자동 방식 배경 보호 자동 / 기존 자동, 자동 RGB 전체 레벨 버튼.
• 배경 보호 체크와 상한 값.
• ＋ 밝기 · 대비 · 채널별 자동: 밝기·대비와 채널별 자동 보정.
• 아래 고정 버튼: 초기화, 보정값 복사….

3.6 저장 막대

• 저장 설정 ▸/▾: 세부 설정 펼치기/접기. 옆에 현재 설정 요약(형식·크기·Well 정보·격자·전체 Plate 수·미연결 수·저장 폴더).
• 선택 N개 저장, 전체 N개 저장(강조 버튼).
• 펼친 설정: 저장 폴더(입력 칸, 선택, 폴더 열기), PNG, 50% 축소, Well 정보, 결과 Well 격자와 색 견본·색상·두께(1–12 px), 아래에 저장 이름 미리보기.

3.7 상태줄

진행 메시지, 실패 이유 보기 (N), 결과 보기, 실패 재시도, 진행 막대, 취소 버튼. 창이 좁으면 결과 메뉴로 묶입니다.

4. 기본 작업 순서 (빠른 시작)

1. ＋ 가져오기 → 이미지 추가…로 이미지를 고르거나, 탐색기에서 파일·폴더를 창에 드롭합니다.
2. 왼쪽 위에서 Plate(96/384)가 맞는지 확인합니다.
3. 전체 보기의 연속 추가 모드에서 필요한 Well 범위를 차례로 드래그합니다. 드래그할 때마다 새 영역이 생깁니다.
4. 목록에서 영역을 더블클릭(또는 F2)해 샘플명 → crop 위치 → 태그를 입력합니다(Tab으로 다음 칸, Enter로 확정).
5. 오른쪽 이지 모드에서 약·중·강을 누르고 보정 강도를 조절합니다. 세밀하게 조절하려면 심화 · RGB 모드를 씁니다.
6. 미리보기를 선택 crop · 출력 검증으로 바꿔 실제 저장 결과를 확인합니다.
7. 저장 설정 ▸에서 저장 폴더·형식을 정하고 선택 N개 저장 또는 전체 N개 저장을 누릅니다.
8. 이어서 작업할 계획이면 Ctrl+S로 프로젝트를 저장합니다. (이미지 결과 저장과 프로젝트 저장은 서로 다른 작업입니다.)

주의: 새로 불러온 이미지에는 전체 Plate 영역 Sample01이 이미 들어 있습니다. crop을 4개 더 만들면 영역은 5개이고 전체 저장에도 5개가 모두 포함됩니다. 전체 Plate가 필요 없으면 영역 작업 → 이 이미지의 전체 Plate 영역 제거로 지우세요(Ctrl+Z로 되돌릴 수 있습니다).

5. 이미지 가져오기

5.1 방법

5.2 폴더 검색 규칙

폴더를 넣으면 하위 폴더를 모두 찾아 다음 조건을 모두 만족하는 파일만 등록합니다.

• 바로 위 폴더 이름이 AnalysisResult (대소문자 무관)
• 확장자를 뺀 파일 이름이 정확히 _combineimage
• 확장자가 BMP, PNG, JPG/JPEG, TIF/TIFF

예: AnalysisResult/_combineimage.bmp는 포함, _combineimage_2.bmp, _combineimage_result.png, 다른 폴더의 _combineimage.bmp는 제외. 이름이 다른 파일은 직접 파일 선택으로 추가하세요. 바로가기·심볼릭 링크·정션은 따라가지 않습니다.

5.3 중복과 실패

• 이미 등록된 경로는 다시 등록하지 않습니다(대소문자·..·UNC/연결 드라이브 표기 차이 포함).
• 파일 하나가 실패해도 나머지는 계속 처리합니다. 상태줄의 실패 이유 보기 (N)에서 파일별 경로와 원인(권한 거부, 파일 없음, 손상, 잠김 등)을 확인하고 내용 복사로 전달할 수 있습니다. 문제를 고친 뒤 실패 항목 다시 시도를 누르세요.
• 프로젝트 → 네트워크 / 접근 진단은 최근 실패와 작업 기록, 실행 권한 상태를 모아 보여 줍니다.

5.4 회사 네트워크·보안 드라이브

1. 탐색기와 384cropper를 모두 일반 권한으로 실행합니다.
2. 드롭이 안 되면 파일 복사 후 Ctrl+V, 그래도 안 되면 경로로 추가를 사용합니다.
3. "읽기 권한 거부"는 회사 보안/DRM 정책이 막은 것입니다. 프로그램은 권한을 바꾸거나 자격 증명을 저장하지 않으므로 관리자에게 접근 허용을 요청하세요.
4. 연결 드라이브(Z: 등) 경로가 열리지 않으면, 같은 사용자 세션의 UNC 경로로 한 번 더 시도합니다.

큰 파일을 읽거나 저장하는 동안 취소를 누르면 "취소 요청됨"이 표시되고, 현재 디코딩/파일 쓰기 단계가 끝나는 다음 안전한 지점에서 멈춥니다.

6. 영역(crop) 만들기와 편집

6.1 Well 좌표

• 96 Well: A1–H12, 384 Well: A1–P24.
• 이미지 전체를 행·열 수로 정수 픽셀 경계로 나눕니다(마지막 경계는 이미지 끝). 저장·미리보기·클릭 판정이 모두 같은 경계를 씁니다.
• 스캐너 여백·기울기·XML 위치 정보는 자동 보정하지 않습니다.

6.2 만들기

• 연속 추가 모드(기본): 전체 보기에서 드래그할 때마다 새 crop이 생깁니다. 클릭만 하면 해당 영역을 선택합니다.
• 다른 모드에서도 Shift+드래그로 새 영역을 만듭니다.
• 드래그 중 Esc는 현재 그리기만 취소합니다.
• 새 영역 이름은 Sample02, Sample03…으로 자동 증가하며 자유롭게 바꿀 수 있습니다.

6.3 수정·이동

• 수정 모드: 선택 영역을 다시 드래그하거나 모서리 손잡이로 크기 변경.
• 이동 모드: 선택 영역 안에서 드래그하면 Well 단위로 이동(Plate 밖으로 나가지 않음).
• crop 위치 칸에 A1-C3처럼 입력하고 Enter 또는 적용. C3-A1처럼 거꾸로 입력해도 정규화합니다. 범위를 벗어나거나 형식이 틀리면 확정하지 않고 입력을 보존하며 이유를 표시합니다.
• 영역 위치는 전체 · 빠른 보기에서만 편집합니다. 선택 crop 보기나 출력 검증 중에는 샘플명·태그·색만 바꿀 수 있습니다.

6.4 샘플명·태그·색

• 목록의 영역 행을 더블클릭하거나 F2를 누르면 표 안에서 바로 편집합니다. Tab / Shift+Tab으로 칸 이동, Enter로 확정 후 미리보기로 돌아가며, Esc는 취소입니다.
• 태그는 파일 이름과 Well 정보에 들어갑니다(비우면 생략).
• 영역 색은 화면에서 영역을 구분하는 용도일 뿐 결과 픽셀과 파일 이름에는 영향이 없습니다. 여러 영역을 선택한 뒤 색을 누르면 일괄 적용됩니다.

6.5 복제·복사·삭제

• Ctrl+D 또는 복제: 같은 위치에 복제(샘플명 뒤에 _복사).
• 오른쪽/아래/왼쪽/위에 복제: 영역 크기만큼 옆에 복제. Plate 밖으로 나가면 만들지 않습니다. 미리보기에서 Ctrl+R(오른쪽), Ctrl+Shift+R(아래).
• 선택 영역에 태그 일괄 적용…: 선택한 영역(이미지 행을 고르면 그 이미지의 모든 영역)의 태그를 한 번에 변경. 빈 값은 태그 삭제.
• 다른 이미지에 영역 복사…: 기본은 추가, 대상의 기존 영역 교체를 체크하면 교체. Plate가 다른 이미지에는 복사하지 않습니다.
• 선택 삭제(Delete 키): 영역 삭제는 실행 취소 가능. 이미지 행을 삭제하면 확인 창이 뜨고(기본 "아니요"), 목록에서만 빠지며 원본 파일은 그대로입니다. 이미지 제거는 실행 취소되지 않습니다.

6.6 현재 영역과 저장 선택

미리보기에서 편집하는 현재 영역과 저장할 영역의 선택은 별개입니다. 목록에서 Ctrl/Shift로 여러 행을 고른 뒤 미리보기에서 다른 crop을 클릭해도 저장 선택은 줄어들지 않습니다. 부모 이미지와 그 아래 영역을 함께 골라도 같은 영역을 두 번 저장하지 않습니다. 선택을 비우려면 영역 작업 → 저장 선택 해제를 사용합니다.

7. 미리보기: 확대·비교·출력 검증

7.1 확대와 이동

• 마우스 휠 또는 − / +: 확대·축소. 배율 목록에서 화면 맞춤, 10–400%를 고를 수 있습니다.
• 가운데 버튼 드래그 또는 스크롤바: 화면 이동.
• 충분히 확대하면 원본 해상도의 필요한 부분만 따로 읽어 선명하게 보여 줍니다("원본 상세").
• 100% 확대(화면)와 50% 축소 저장(결과)은 서로 다른 설정입니다.

7.2 비교

• 원본: 보정 전 이미지를 봅니다.
• 미리보기를 클릭해 포커스를 준 뒤 Space를 누르고 있는 동안 임시로 원본을 봅니다.
• A/B 비교: 같은 위치를 경계선으로 나눠 왼쪽은 원본(A), 오른쪽은 보정(B)으로 봅니다. 경계선 손잡이(↔)를 드래그해 비율을 바꿉니다(미리보기 폭 600 px 이상 필요).

7.3 빠른 보기와 출력 검증

• 빠른 보기 · 근사: 조작에 빠르게 반응하도록 축소본이나 화면 크기의 조각에 보정을 적용합니다. 미세한 점이나 강한 형광에서는 저장 결과와 조금 다를 수 있습니다.
• 출력 검증: 선택한 crop 하나를 실제 저장과 같은 순서로 계산합니다. 원본 crop → 원래 해상도에서 보정 → (선택 시) 50% 축소 → 결과 Well 격자 → 화면 표시. 원본·영역·보정·저장 옵션이 바뀌면 다시 계산합니다. A/B에서 A는 결과 격자가 없는 원본, B는 저장 결과입니다.
• JPEG는 "JPEG 압축 전"으로 표시됩니다. 손실 압축 후의 픽셀까지 재현한 화면은 아니므로 정확한 픽셀 보관이 필요하면 PNG나 BMP를 선택하세요.
• 원본 다시 읽기: 네트워크 복구 등으로 이전 읽기 실패를 다시 시도합니다. 원본 파일이 바뀐 것이 감지되면(크기·수정 시각) 이전 요청으로 조용히 저장하지 않고 오류를 알립니다. 다시 등록한 뒤 영역과 보정을 확인하세요.

8. RGB 보정

보정은 원본 이미지 단위의 설정입니다. 같은 이미지의 모든 crop에 똑같이 적용되며, 선택 crop만 보고 있어도 적용 범위는 이미지 전체입니다. 이지/심화 모드 전환은 수치를 바꾸지 않습니다.

8.1 계산 순서

보정값은 한 번 계산한 256단계 표(LUT)로 적용하며 순서는 항상 같습니다.

1. RGB 공통 레벨(검정점·감마·흰점)
2. 채널(R/G/B)별 레벨
3. 밝기(곱하기)
4. 대비(가운데 127.5 기준 고정)
5. 배경 보호(켠 경우: 상한 이하 값은 밝게 만들지 않고, 그 위 32단계에서 부드럽게 원래 보정으로 연결)
6. 보정 강도(원본과 보정 결과의 차이에 곱함, 100% 초과 시 같은 방향으로 외삽)
7. 0–255로 자른 뒤 반올림

미리보기·출력 검증·저장이 모두 이 표를 씁니다.

8.2 이지 모드: 형광 프리셋과 강도

• 약·중·강: 현재 원본의 RGB 히스토그램으로 공통 검정점·흰점과 감마를 계산합니다(배경 보호 꺼짐). 이미지마다 결과가 다르며 심화 모드에서 이어서 조절할 수 있습니다. 세 프리셋은 검정점·흰점이 같고 감마만 다릅니다.
• 보정 강도 (%): 슬라이더는 0–100%, 숫자 칸은 100%를 넘는 값도 입력 가능합니다(예: 150, 175, 200 입력 후 Enter). 슬라이더가 끝에 있어도 입력한 숫자는 그대로 유지됩니다. 0 이상의 유한한 숫자만 허용합니다.

8.3 심화 모드

• RGB / R / G / B: 편집할 채널 선택. 히스토그램에 검정점·흰점 위치가 점선으로 표시됩니다.
• 검정점 < 흰점, 둘 다 0–255. 감마 0.10–5.00. 밝기·대비 0.00–3.00. 배경 보호 상한 0–128.
• 입력 칸은 Enter 또는 다른 칸으로 이동할 때 반영되며, 잘못된 값이면 이유를 표시하고 이전 값을 유지합니다.

8.4 자동 보정

• 배경 보호 자동: 검은 여백(0)을 제외하고 어두운 배경의 과도한 증폭을 줄이도록 계산, 배경 보호 켬·강도 70%.
• 기존 자동: 전체 히스토그램 양끝 0.5%를 기준으로 계산, 배경 보호 끔·강도 100%.
• 자동 RGB 전체 레벨: 세 채널을 합쳐 RGB 공통 검정점·흰점을 계산(밝기·대비는 1.0).
• 채널별 자동 보정: R/G/B 각각 계산. 유효 범위가 없는 채널은 기본 레벨 유지.
• 계산 중 직접 값을 바꾸면 늦게 도착한 자동 결과가 그 입력을 덮지 않습니다.
• 배경 보호는 밝기 기준의 보조 기능이며 생물학적 배경 분할이 아닙니다.

8.5 초기화·복사·실행 취소

• 초기화: 레벨 0/1/255, 밝기·대비 1, 강도 100%, 배경 보호 끔.
• 보정값 복사…: 계산된 수치를 다른 이미지에 그대로 복사합니다(대상에서 자동 재계산하지 않음).
• Ctrl+Z / Ctrl+Y: 현재 이미지의 보정·영역 변경을 되돌리거나 다시 실행합니다(연속 입력은 한 단계로 묶임, 최대 40단계).

8.6 LUT 진단과 저장 전 확인

강한 강도·대비는 밝기 순서를 뒤집거나 여러 입력을 한 출력으로 모을 수 있습니다. 오른쪽의 LUT 문구는 채널별 감소 구간 수, 최대 하락, 출력 단계 수, 포화 항목 수를 보여 줍니다(영상 픽셀 비율이 아니라 LUT 표의 진단입니다). 감소 구간이 있거나 한 채널의 출력이 두 단계 이하이면 저장 전에 보정 결과 확인 창이 뜹니다. 기본은 "아니요"(설정으로 돌아가기)이고, "예"를 누르면 현재 값으로 저장합니다. 프로그램이 값을 임의로 고치지 않습니다.

9. 결과 이미지 저장

9.1 절차

1. 저장 설정 ▸을 펼칩니다.
2. 저장 폴더를 입력하거나 선택으로 고릅니다(없으면 저장할 때 폴더 선택 창이 뜹니다).
3. 형식과 옵션을 고릅니다: PNG(끄면 원본 형식), 50% 축소, Well 정보, 결과 Well 격자(색·두께).
4. 아래 저장 이름 미리보기에서 파일 이름과 크기를 확인합니다.
5. 선택 N개 저장(목록에서 고른 영역) 또는 전체 N개 저장(모든 이미지의 모든 영역)을 누릅니다.
6. 진행 중에는 취소로 멈출 수 있습니다. 끝나면 상태줄에 저장 완료 · N개 저장 / N개 오류가 표시됩니다.

9.2 파일 이름

원본파일명_샘플명_Well범위_태그[_50resized][_번호].확장자
원본파일명_샘플명_Well범위_태그[_50resized][_번호].확장자.metadata.json   (Well 정보를 켠 경우)

• 예: plate1_처리군_B3-F8_D5.png, 태그가 없으면 plate1_Sample01_A1-P24.bmp.
• 파일 이름에 쓸 수 없는 문자(<>:"/\|?* 등)는 _로 바꾸고, Windows 예약 이름(CON, PRN 등)은 앞에 _를 붙입니다.
• 이름이 길면(Windows 255자·전체 경로 259자 기준) Well 범위와 _50resized는 유지하고 원본명·샘플명·태그를 줄인 뒤 ~ + 식별자(해시 10자리)를 붙입니다. 원래 이름·태그는 Well 정보에 그대로 남습니다.
• 같은 이름의 이미지 또는 Well 정보 파일이 이미 있으면 _2, _3…을 붙여 절대 덮어쓰지 않습니다. 이미지와 정보 파일은 항상 같은 번호를 씁니다. 최종 번호는 실제 저장할 때 정해집니다.

9.3 형식별 저장 방식

Well 정보를 켜면 모든 형식에 .metadata.json을 함께 만듭니다. 기록 항목: 프로그램(application), 버전(version, 2.3.0), schema_version(1), 원본 파일명과 크기, Plate, Well 범위, 샘플명, 태그, 영역 색, crop 픽셀 위치, 결과 크기와 형식, 옵션(PNG 변환·50%), 보정값, 결과 격자 설정. 원본 폴더 경로는 기록하지 않습니다. Well 정보를 켜고 끄는 것은 디코딩한 픽셀을 바꾸지 않습니다.

9.4 결과 Well 격자

결과 Well 격자를 켜면 결과 이미지의 실제 픽셀에 Well 경계선과 테두리를 그립니다. 두께(1–12 px)는 최종 저장 이미지 기준이며 50% 축소 후에 그립니다. 화면 격자·눈금·영역 색은 결과에 들어가지 않는 화면 표시입니다.

9.5 결과 확인과 실패 재시도

• 결과 보기: 이번 저장의 항목별 결과(저장 완료·실패·취소·시작 전), 원본, 샘플, Well, 저장 경로 또는 실패 이유를 표로 보여 줍니다. 오류나 취소가 있으면 자동으로 열립니다.
• 실패 재시도(또는 결과 창의 실패만 다시 저장): 실패한 항목만 처음 요청한 설정 그대로(원본·영역·보정·폴더·옵션) 다시 저장합니다. 이후 화면에서 바꾼 값은 섞이지 않습니다. 현재 값으로 저장하려면 새로 저장하세요. 원본이 그사이 바뀌었으면 재시도도 실패로 표시됩니다.
• 실패·취소된 항목은 이번 작업이 만든 미완료 파일만 지웁니다. 정리에도 실패하면 남은 경로를 알려 줍니다. 먼저 끝난 다른 결과는 유지됩니다.

10. 프로젝트(작업 파일) 저장과 열기

10.1 무엇이 저장되나

.cropper.json 프로젝트에는 원본 경로, Plate, 이미지 크기, 영역(샘플명·태그·Well 범위·색), 다음 샘플 번호, 보정값, 저장 옵션(폴더·PNG·50%·Well 정보·격자)이 들어갑니다. 원본 픽셀은 들어가지 않습니다. 결과 엑셀 창의 ATP 설정은 저장하지 않습니다.

10.2 저장·열기

• Ctrl+S: 작업 저장(처음이면 이름 지정). Ctrl+Shift+S: 다른 이름으로 저장. 저장은 임시 파일에 쓴 뒤 한 번에 교체하므로 실패해도 이전 파일이 그대로 남습니다.
• Ctrl+O: 작업 열기. 여는 동안 편집이 잠기고, 취소하면 이전 작업을 그대로 유지합니다.
• 원본을 찾을 수 없거나 읽을 수 없는 이미지는 미연결 항목으로 설정을 보존합니다. 원본을 복구한 뒤 ＋ 가져오기 → 실패한 파일 다시 시도를 누르거나 프로젝트를 다시 열면 연결됩니다. 미연결 항목도 다시 저장할 때 그대로 유지됩니다.
• 원본 크기가 저장 당시와 다르면 영역을 복원하지 않고 이유를 표시합니다.
• 새 작업·열기·종료 시 저장하지 않은 변경이 있으면 저장 여부를 묻습니다.

10.3 호환성

2.3.0은 2.2.1과 같은 형식(schema_version 1)으로 저장합니다. 2.2.1(및 V2 계열)에서 만든 파일을 그대로 열 수 있고, 2.3.0에서 저장한 파일도 2.2.1에서 열 수 있습니다. 결과 격자 색은 파일에 대문자(#ABCDEF)로 저장됩니다(이전과 동일).

11. RGB 채널 Merge

같은 위치에서 같은 크기로 찍은 여러 이미지의 채널을 골라 한 장의 컬러 이미지로 합칩니다.

11.1 절차

1. 합칠 이미지를 먼저 목록에 등록합니다.
2. 상단 RGB merge를 누릅니다.
3. 출력 채널 R / G / B마다 등록된 원본 이미지와 원본 성분(R, G, B 또는 L=밝기)을 고릅니다. 쓰지 않을 채널은 "선택 안 함 · 검정".
4. 축소 미리보기를 확인합니다.
5. Merge 저장…(저장만) 또는 저장 후 가져오기…(저장한 결과를 가져올 Plate로 목록에 추가)를 누르고 PNG 또는 BMP 이름을 정합니다.

11.2 규칙

• 한 채널 이상 선택해야 하며 선택한 이미지의 크기가 모두 같아야 합니다. 자동 정렬·크기 맞춤은 하지 않습니다.
• 전체 원본의 성분을 합칩니다. crop 범위·보정값·결과 격자·Well 정보는 적용하지 않습니다.
• 2.3.0: 이미 있는 파일 이름을 고르면 덮어쓰기 확인 없이 이름_2.png, 이름_3.png…으로 저장하고 "같은 이름의 파일이 있어 번호를 붙였습니다"라고 알려 줍니다. 기존 파일은 절대 덮어쓰지 않습니다.
• 목록에서 원본을 제거하면 Merge 창에 "제거된 입력"으로 표시되고 다른 이미지로 자동 대체하지 않습니다. 원본이 바뀌었으면 저장하지 않고 이유를 알려 줍니다.
• 저장 중 취소하면 만들던 파일을 지웁니다.

12. 이미지·분석·ATP 통합 결과 엑셀

기준 _combineimage, 같은 폴더의 분석 표, 별도의 ATP 측정 파일을 Well 위치(A1…P24)로 결합해 하나의 XLSX로 만듭니다.

12.1 창 열기

• 상단 결과 엑셀(좁은 창: 작업 → 결과 엑셀).
• ATP 엑셀/CSV 파일을 메인 창에 드롭해도 열립니다(이미지와 함께 드롭하면 이미지를 먼저 등록한 뒤 열림).
• 작업대 실행기 또는 명령줄 --open-result로 시작하면 바로 열립니다(13장).

12.2 절차

1. 기준 이미지: 목록에 등록된 이미지 중에서 고르거나 이미지 선택…으로 파일을 고릅니다. 폴더를 넣으면 그 안의 _combineimage(BMP/PNG/JPG/JPEG/TIF/TIFF)가 정확히 1개일 때 사용합니다. 8비트 RGB 이미지여야 합니다.
2. ATP 파일: ATP 선택…, 창에 드롭, 또는 탐색기에서 복사 후 Ctrl+V.
3. 기준 이미지가 있는 폴더 한 곳의 CSV/TSV/XLSX/XLSM 표를 자동 스캔합니다(하위 폴더는 섞지 않음). 읽을 수 없는 표나 폴더는 스캔 제외와 사유로 표시되고, 나머지는 계속 사용합니다.
4. 발견한 분석 표 목록에서 더블클릭으로 포함(✓)/제외합니다. ATP 파일에 표가 여러 개면 ATP 표에서 하나를 고릅니다.
5. Plate(384/96)를 확인합니다.
6. ATP standard (µM) 칸을 확인합니다. 384 Well 기본값은 24번 열 A24–P24의 위에서 아래 순서 0, 0, 0.00064, 0.00064, 0.0032, 0.0032, 0.016, 0.016, 0.08, 0.08, 0.4, 0.4, 2, 2, 10, 10 µM입니다. 형식은 한 줄에 Well 농도 포함(1/0)(예: A24 0 1), 또는 농도 16줄만 붙여넣기. 24번 열 기본값으로 되돌립니다. 96 Well은 실제 standard Well을 직접 입력해야 합니다.
7. 회귀 방식: 절편 포함(기본, 모든 유효 반복 표준점의 비가중 최소제곱 직선) 또는 Blank 고정(포함된 0 µM 표준의 평균 RLU를 절편으로 고정). 두 방식 모두 RLU = 기울기 × 농도 + 절편.
8. 표준곡선 확인으로 회귀식·R²·점 수·범위·음수로 환산되는 표준 수를 확인합니다.
9. 샘플 희석 배수를 입력합니다(기본 1, standard Well은 항상 1). 샘플 농도 = (원시 RLU − 절편) / 기울기 × 희석 배수.
10. 필요하면 Well 이미지와 Plate 전체 이미지 삽입을 끕니다(더 빠르고 작은 파일).
11. 통합 결과 엑셀 저장… → 파일 이름(기본 ATP파일명_통합결과.xlsx). 같은 이름이 있으면 _2, _3…을 붙입니다.
12. 진행 중 취소를 누를 수 있습니다(큰 이미지 디코딩·엑셀 압축은 현재 단계가 끝나야 멈춤). 취소·실패 시 저장 폴더에 임시 파일을 남기지 않습니다.

12.3 결과 시트

엑셀에서 ATP standard의 노란 칸(농도, 포함 1/0, 희석 배수, 회귀 방식)을 바꾸면 수식으로 환산값과 맵이 다시 계산됩니다. 파일에는 최초 계산값도 함께 저장되어 수식 계산을 못 하는 뷰어에서도 처음 값은 보입니다.

12.4 해석 규칙

• 빈 ATP 칸은 "ATP 미측정"이며 숫자 0과 구분합니다. 실제 0은 0으로 유지합니다.
• 음수 환산값은 0으로 자르지 않고 "음수 환산값"으로 표시합니다. 표준 범위 밖은 "표준 범위 미만/초과"로 표시합니다. LOD/LOQ나 생존율로 해석하지 않습니다.
• 분석 수치는 원본 파일의 원시 단위를 유지합니다(임의의 µm² 변환 없음). ColonyArea의 item count는 목록의 항목 수로 CellCount와 다른 지표입니다.
• 결과 이미지는 보정 전 원본 축소본이며 Well 위치는 이미지 전체의 균등 분할입니다.

12.5 지원하는 표

CSV(UTF-8, CP949, UTF-16)/TSV, XLSX/XLSM의 명시적 Well 행렬(열 머리글 1–24 또는 C1–C24, 행 A–P) 또는 Well 열이 있는 표, ColonyArea 목록. XLSM의 매크로는 실행하지 않고, 엑셀 수식은 마지막으로 저장된 계산값을 읽습니다. 구형 .xls는 Excel에서 .xlsx로 저장한 뒤 사용하세요. 한도: CSV 50MB, 엑셀 10만 행·512열. 이 프로그램이 만든 통합 결과 엑셀은 다시 스캔 대상에 넣지 않습니다.

13. 명령줄 실행 옵션

소스 실행 시에는 python 384cropper_GUI_YK.py …로 같은 옵션을 씁니다. --self-test, --large-self-test, --probe-access는 Windows 수용 시험용입니다.

14. 파일 이름과 저장 위치 정리

15. 설정 항목의 의미

16. 안전 규칙 (원본 보존)

1. 원본 이미지·분석 표·ATP 파일은 읽기만 합니다. 수정·이동·삭제하지 않습니다.
2. 덮어쓰지 않습니다. 결과 이미지·Well 정보·Merge·통합 엑셀은 항상 새 파일로 만들고, 같은 이름이 있으면 번호를 붙입니다. 입력 파일을 결과 경로로 지정하면 거부합니다.
3. 실패·취소 시 자기 파일만 정리합니다. 이번 작업이 새로 만든 미완료 파일만 지우고, 이미 있던 파일과 먼저 완료된 결과는 건드리지 않습니다.
4. 원본이 바뀌면 멈춥니다. 등록 후 원본의 크기·수정 시각이 바뀌면 미리보기·저장·재시도·Merge·엑셀 저장을 중단하고 알립니다.
5. 프로젝트는 원자적으로 저장합니다. 저장 중 실패해도 이전 프로젝트 파일이 그대로 남습니다.
6. 권한·보안 설정을 바꾸거나 자격 증명을 저장하지 않습니다.

17. 자주 나오는 오류와 해결

18. 자주 묻는 질문 (FAQ)

Q. 전체 저장했더니 파일이 하나 더 나왔어요. A. 새 이미지에 기본으로 들어 있는 전체 Plate 영역 Sample01 때문입니다. 필요 없으면 이 이미지의 전체 Plate 영역 제거를 사용하세요.

Q. 미리보기와 저장 결과가 조금 달라 보여요. A. 빠른 보기는 축소본으로 계산한 근사 화면입니다. 선택 crop + 출력 검증으로 보면 저장과 같은 순서로 계산한 화면입니다. JPEG는 압축 전 픽셀입니다.

Q. 보정을 crop마다 다르게 할 수 있나요? A. 아니요. 보정은 원본 이미지 단위입니다. 다른 보정이 필요하면 원본을 따로 등록해 작업하세요.

Q. 100%보다 강하게 보정하려면? A. 강도 숫자 칸에 150, 200 등을 입력하고 Enter를 누르세요. 슬라이더는 100%에서 멈추지만 입력값은 유지됩니다.

Q. 이전 버전(2.2.1)에서 저장한 프로젝트를 열 수 있나요? A. 네. 형식이 같습니다. 2.3.0에서 저장한 파일도 2.2.1에서 열립니다.

Q. Well 정보의 version이 2.1.0에서 2.3.0으로 바뀌었어요. A. 2.3.0부터 실제 기록한 프로그램 버전을 적습니다. 나머지 항목과 schema_version(1)은 같으므로 기존에 정보를 읽던 도구는 그대로 쓸 수 있습니다.

Q. Merge 저장 때 덮어쓰기 확인이 안 떠요. A. 2.3.0부터 같은 이름이 있으면 덮어쓰지 않고 _2를 붙여 저장하므로 확인이 필요 없습니다.

Q. 엑셀에서 샘플명이 비어 있어요. A. 기준 이미지가 목록에 등록되어 있고 그 이미지에 영역이 있어야 샘플명·태그가 들어갑니다. 2.3.0은 경로 표기 차이를 무시하고 찾습니다. 전체 Plate 영역만 있으면 그 이름이 쓰이고, 더 구체적인 영역이 있으면 그것을 우선합니다.

Q. ATP 설정도 프로젝트에 저장되나요? A. 아니요. 결과 엑셀 창의 설정은 그 창에서만 쓰입니다. 결과 엑셀의 ATP standard 시트에 사용한 값이 남습니다.

Q. 작업 중 창을 닫으면? A. 진행 중인 작업에 취소를 요청하고, 작업이 안전하게 멈춘 뒤 저장 여부를 물어보고 닫습니다.

19. 단축키

입력 칸에서는 텍스트 편집과 한글 입력을 우선합니다. 커서가 입력 칸에 있을 때 Ctrl+Z/Ctrl+Y·Ctrl+V는 영역·보정 실행 취소나 파일 붙여넣기로 동작하지 않습니다.

20. 지원 범위와 한계

• 8비트 정지 이미지(RGB, RGBA, 회색조, 팔레트), 96/384 Plate를 지원합니다. 16비트 보존, 다중 페이지 TIFF, 스캐너 XML 위치 보정, 이미지 정렬, crop별 독립 보정은 지원하지 않습니다.
• 약 1억 5천만 화소의 대형 Plate 이미지를 열 수 있도록 Pillow의 대형 이미지 경고를 끄고 사용합니다(사용자가 직접 고른 로컬/공유 파일만 엽니다).
• 대용량 원본은 한 번에 하나씩 처리하고, 오래된 미리보기 요청은 버립니다. 화면 크기·DPI·네트워크 속도에 따라 표시와 처리 시간이 달라집니다.
• 형광 프리셋과 자동 보정은 시각적 확인을 돕는 기능입니다. 정량 분석은 원본 분석 값으로 하세요.
• Windows 전용 프로그램입니다(드래그 앤드 드롭, 클립보드 파일 붙여넣기, 연결 드라이브 처리).

21. 2.3.0에서 달라진 점

• 창 제목·도움말·배지·Well 정보 version을 2.3.0으로 통일(정보 구조 schema_version 1 유지).
• RGB merge: 같은 이름이 있으면 _2, _3…으로 저장(덮어쓰기 확인 없음, 기존 파일 보존).
• 결과 엑셀: 폴더 입력에서 _combineimage.jpeg 인식, 경로 표기가 달라도 샘플명·태그 연결, 분석 폴더 오류 시 스캔 계속, 취소·실패 시 임시 파일 미잔류, 너무 작은 이미지에 명확한 오류.
• 새 실행 옵션 --open-result, --help. 실행 파일 이름 384cropper_YK_2.3.0.exe.
• 이미지가 많은 프로젝트를 더 빨리 엽니다(경로 표시 계산 1회).

자세한 변경과 검증 내용은 CHANGELOG_V2.3.0.md와 REFACTOR_NOTES.md를 참고하세요.

Scalebar GUI YK 1.5.0 사용설명서

현미경·스캐너로 찍은 원본 이미지에 실제 길이(µm)에 맞는 스케일바와 라벨을 그려 새 파일로 저장하는 프로그램입니다. 원본 파일은 절대 수정하거나 덮어쓰지 않습니다.

1. 이 프로그램이 하는 일

• 이미지 크기(해상도)를 보고 어느 장비(Microscope / V5 scanner / V5.5 scanner)로 찍었는지 이미지마다 자동으로 판단합니다.
• 장비와 배율(2X / 4X / 10X / 20X)에 맞는 픽셀 환산값으로 스케일바 길이를 계산해 그립니다.
• 스케일바 아래에 "100µm", "(Microscope, 4X)" 같은 라벨을 넣습니다(켜고 끌 수 있음).
• 결과 파일 이름에 배율·장비·길이를 넣고, 파일 안에 설정값(메타데이터)을 기록합니다. JPG는 윈도우 탐색기의 "태그"에서 바로 보입니다.

2. 다른 도구와의 관계

• Scalebar GUI는 혼자 동작합니다. 현미경·스캐너가 저장한 이미지를 바로 읽으며, 다른 도구의 결과가 필요하지 않습니다.
• 작업대의 다른 세 도구(Auto OptiResolve, 384cropper, 이미지 그리드 합치기)는 별개의 프로그램입니다. 정해진 순서가 없으니 필요한 도구만 골라 쓰거나 이 프로그램만 써도 됩니다.
• 런처(YK MBD Image Workbench)는 이 프로그램을 여는 방법 중 하나일 뿐입니다. 프로그램을 직접 실행해도 똑같이 동작합니다.

3. 보정값이 맞는 이미지 / 맞지 않는 이미지 (중요)

• 스케일바는 크기를 바꾸기 전에 넣으세요. 스케일바가 그려진 이미지는 나중에 확대·축소해도 막대가 이미지와 같이 변하므로 비율이 맞습니다. 반대로 이미 크기를 바꾼 이미지에 이 프로그램으로 스케일바를 넣으면 틀린 길이가 됩니다.
• 스캐너 이미지는 deconvolution된 single well 원본 이미지를 사용하세요(1.3.1부터의 안내).

장비 원본 크기: Microscope 1920×1080, V5 scanner 1900×1400, V5.5 scanner 2200×2200. 이 크기와 정확히 같을 때만 자동 감지됩니다.

4. 화면 구성

창은 왼쪽(목록·설정), 오른쪽(미리보기), 아래(저장 폴더·실행)로 나뉩니다.

4.1 이미지 목록 (왼쪽 위)

글자 색: - 파랑: 자동 감지된 장비가 [수동 장비]와 다름 (그 이미지는 감지된 장비로 처리) - 주황: 해상도를 알 수 없어 [수동 장비]로 처리 - 빨강: 강제 옵션 때문에 감지된 장비와 다른 장비로 처리

목록 아래 요약 줄(예: "4개 · 적용 장비: Microscope 2, V5 scanner 1, V5.5 scanner 1 (혼합)")과 색 설명이 있습니다.

버튼: - [추가…]: 파일 선택 창에서 이미지 추가(여러 개 가능) - [선택 삭제]: 목록에서 고른 항목 제거(키보드 Delete도 가능). 파일은 지워지지 않습니다. - [모두 지우기]: 목록 비우기

파일이나 폴더를 창 위로 끌어다 놓아도 추가됩니다. 폴더를 놓으면 그 폴더 바로 안의 지원 이미지가 추가됩니다(하위 폴더는 제외). 이미 목록에 있는 파일은 다시 추가되지 않습니다.

4.2 일반 탭

라벨 2행은 켠 항목만 괄호 안에 쉼표로 이어 붙입니다: 둘 다 켜면 "(Microscope, 4X)", 장비만 "(Microscope)", 배율만 "(4X)", 둘 다 끄면 2행 없음.

4.3 고급 탭

• 위치는 슬라이더 또는 숫자칸으로 바꿉니다. 둘은 항상 같은 값을 보여 줍니다.
• 숫자칸: 입력하는 동안에는 글자를 바꾸지 않습니다. Enter 또는 다른 칸으로 이동하면 범위에 맞추고 소수 1자리로 정리합니다. 칸을 비우거나 "."만 두면 마지막 올바른 값으로 돌아갑니다.
• 마우스 휠: 슬라이더·숫자칸 위에서 한 칸 = 0.2 % (두께/폰트는 1), ▲▼ 버튼 = 1.
• 콤보박스(배율·장비·색상·확장자) 위에서는 휠로 값이 바뀌지 않게 막아 두었습니다.

4.4 미리보기 (오른쪽)

• 이미지 + 스케일바: 목록에서 선택한 이미지를 줄여서 보여 주고, 막대·두께·글자를 같은 비율로 줄여 그립니다. 실제 결과와 위치·비율이 같습니다.
• 스케일바만: 이미지 없이 막대와 라벨만 실제 픽셀 크기로 보여 줍니다.
• 아래 정보 줄: 파일명 · 해상도 · 적용 장비(출처) · 배율 · "68 px/100 µm → 막대 68 px". 막대가 이미지보다 길거나, 스케일에 소수가 있어 라벨에 정수만 표시될 때, Arial Bold를 못 찾아 대체 글꼴을 쓸 때 안내가 함께 나옵니다.
• 미리보기는 선택한 이미지 한 장만 메모리에 보관합니다(작게 줄인 사본과 원본 크기만).

4.5 저장 폴더 (아래)

• 현재 저장 폴더 경로와 상태("프로그램 폴더(기본값) · 쓰기 가능" 등)가 보입니다.
• [변경…]: 다른 폴더 선택(쓸 수 없는 폴더는 다시 고르게 함). 선택은 다음 실행에도 기억됩니다.
• [열기]: 탐색기로 폴더 열기
• [기본값]: 프로그램 폴더로 되돌리기

4.6 실행 줄 (맨 아래)

[도움말] · 상태 메시지 · 진행 막대 · [취소] · [스케일바 실행]

5. 사용 방법 (단계별)

5.1 원본 이미지에 스케일바 넣기 (기본)

1. [추가…]를 누르거나 이미지 파일을 창에 끌어다 놓습니다.
2. 목록에서 감지 장비/적용 장비가 맞는지 확인합니다. 첫 이미지가 자동으로 선택되어 미리보기에 나옵니다.
3. 일반 탭에서 배율을 고르고 스케일 크기(µm)를 입력합니다.
4. 필요하면 라벨·색상·위치·두께·폰트를 조정하고 미리보기로 확인합니다. 목록의 다른 이미지를 누르면 그 이미지로 미리보기가 바뀝니다.
5. 아래 저장 폴더를 확인합니다.
6. [스케일바 실행]을 누릅니다. 진행 막대와 상태줄에 "처리 중… 3/10: 파일명"이 표시됩니다.
7. 끝나면 결과창에 "전체 N개 중 성공 N개, 실패 0개"와 저장 폴더가 표시됩니다.

5.2 여러 장비 이미지가 섞였을 때

1. 모두 추가하면 각 행의 적용 장비가 해상도에 따라 자동으로 정해집니다(파랑 = 수동 장비와 다른 자동 감지).
2. [스케일바 실행]을 누르면 "장비 확인" 창에 장비별 개수(예: "Microscope: 3개 (자동 2 · 수동 1)")가 나옵니다.
3. 내용이 맞으면 [확인], 아니면 [취소] 후 설정을 고칩니다.
4. 결과 파일 이름·라벨·막대 길이는 이미지마다 그 이미지의 적용 장비로 만들어집니다.

5.3 크롭한 이미지

1. 크롭 이미지를 추가하면 감지 장비가 "알 수 없음", 적용 장비가 "(수동)"으로 표시됩니다(주황).
2. 일반 탭의 [수동 장비]를 그 이미지를 찍은 장비로 바꿉니다. 목록의 적용 장비가 바로 바뀝니다.
3. 실행합니다.

5.4 크롭 크기가 다른 장비 원본 크기와 같을 때

예: V5.5 스캔 이미지를 1920×1080으로 잘랐더니 "Microscope (자동)"으로 나옴. 1. [수동 장비] = V5.5 scanner 2. [모든 이미지에 수동 장비 강제] 켜기 → 모든 행이 "V5.5 scanner (강제)", 감지와 다른 행은 빨강 3. 실행 → 확인창의 "감지 장비와 다른 장비로 강제 처리될 이미지: N개"를 확인하고 [확인] 4. 다른 장비 이미지와 섞여 있다면 강제는 모두에게 적용되므로, 장비별로 나누어 실행하세요.

5.5 위치·크기 조정

• 고급 탭 X/Y 슬라이더를 끌거나 숫자를 입력합니다. 오른쪽 아래 기본 위치는 X 90 %, Y 90 %.
• 막대를 정확히 오른쪽 아래 모서리에 붙이려면 X 100, Y 100 — 단, 막대는 (길이+1)×(두께+1) 픽셀로 그려지므로 마지막 1픽셀 줄은 이미지 밖으로 잘립니다. 약간 안쪽(예: 98–99 %)을 권장합니다.
• 라벨 글자는 막대 아래(막대 끝 + 4 px)에 가운데 정렬됩니다. Y를 너무 크게 하면 글자가 이미지 밖으로 잘리니 미리보기로 확인하세요.

5.6 색상 직접 고르기

1. [Custom…] → 색 선택 → [확인]
2. 색상이 Custom으로 바뀌고 옆 네모에 색이 표시됩니다. 메타데이터에는 color:Custom과 실제 색(color_hex:#RRGGBB)이 함께 기록됩니다.

5.7 출력 형식

• same: 원본과 같은 확장자(대소문자 그대로, 예 .JPG).
• .jpg: 품질 95로 저장. 메타데이터는 EXIF(탐색기 "태그").
• .png / .tif: 무손실. 메타데이터는 XMP.
• .bmp: 무손실, 메타데이터 없음.

5.8 저장 폴더가 쓰기 불가일 때 (예: Program Files 안의 EXE)

1. 저장 폴더 행에 빨간 글씨 "쓰기 불가 — 실행할 때 저장할 폴더를 선택하게 됩니다"가 보입니다.
2. [스케일바 실행] → 안내창 → 폴더 선택 창에서 문서/바탕 화면 등 쓸 수 있는 폴더를 고릅니다.
3. 선택한 폴더는 기억되어 다음부터 바로 사용됩니다. 관리자 권한으로 실행할 필요는 없습니다.

5.9 중간에 멈추기

• [취소]: 지금 저장 중인 이미지까지 마친 뒤 멈춥니다. 결과창에 성공/실패/미처리 수가 나옵니다.
• 처리 중 창 닫기: 확인 후 같은 방식으로 멈추고 종료합니다.
• 처리 중에는 목록 변경, 저장 폴더 변경, 배율·장비·색상·확장자·숫자 설정 변경이 잠깁니다(이미 시작한 작업은 시작 시점 설정으로 끝까지 진행).

5.10 결과 확인

• JPG: 탐색기에서 파일 오른쪽 클릭 → 속성 → 자세히 → 태그.
• 태그 내용 예: Version:1.5.0; equip:V5 scanner; mag:4X; scale_um:100.0; color:White; XY:(90.0,90.0); thk_px:10.0; font_pt:40.0; src_res:1900x1400; detected_equip:V5 scanner; applied_equip:V5 scanner; equip_source:auto; px_per_100um:59; bar_length_px:59; color_hex:#FFFFFF

6. 입력·출력 파일 규칙

• 입력 형식: .jpg .jpeg .png .bmp .tif .tiff (한글·공백·긴 경로 가능). 16비트·흑백 이미지는 8비트 컬러로 저장됩니다. 원본의 EXIF/색 프로필은 결과에 복사되지 않습니다.
• 출력 이름: 원본이름_(배율_장비_스케일umscale).확장자 예: sample.jpg → sample_(4X_Microscope_100umscale).jpg, scan.tif → scan_(10X_V5.5 scanner_50umscale).tif
• 스케일에 소수가 있으면 이름과 라벨에는 정수 부분만 들어갑니다(12.5 µm → 12umscale, "12µm"). 막대 길이는 12.5 µm로 계산됩니다. 혼동을 피하려면 정수 µm를 쓰세요.
• 같은 이름이 이미 있으면 …umscale)_2.jpg, _3 … 을 붙여 새로 만듭니다. 기존 파일과 원본은 절대 덮어쓰지 않습니다. 결과창에 번호가 붙은 개수가 표시됩니다.
• 저장 위치: 기본은 프로그램(EXE) 폴더. [변경…]으로 바꾼 폴더는 %LOCALAPPDATA%\ScalebarGUI_YK\settings.json에 기억됩니다.

7. 스케일바 길이 계산과 정밀도

막대 길이(px) = int( 100µm당 px × 스케일(µm) ÷ 100 )     ← 소수점 이하 버림

알아 둘 점(이전 버전과 동일하게 유지): - 소수점 이하는 버립니다: V5 2X 100 µm = 29.5 → 29 px. - 그려지는 막대는 계산값보다 가로·세로 1픽셀 큽니다(길이 68 → 화면상 69 px, 두께 10 → 11 px). - V5.5 scanner의 2X(43)·10X(213)는 4X(85)의 정확한 비례값(42.5, 212.5)과 약간 다릅니다(기록된 값 그대로 사용). - 장비를 잘못 고르면 오차가 큽니다. 예: V5 이미지를 Microscope 4X로 처리하면 68 px vs 59 px(+15.3 %). 1.5.0은 원본 크기 이미지의 장비를 자동으로 맞춥니다.

8. 안전 규칙 (원본 보존)

1. 원본 파일은 읽기만 합니다. 수정·삭제·덮어쓰기 하지 않습니다.
2. 결과는 항상 새 파일입니다. 같은 이름이 있으면 번호를 붙입니다.
3. 저장 중 오류가 나면 만들다 만 결과 파일은 지웁니다.
4. 처리는 시작 시점 설정의 사본으로 진행되므로, 도중에 화면 설정이 바뀌어도 결과가 섞이지 않습니다.
5. 보정값은 원본 크기 이미지에만 유효합니다(3절).

9. 자주 나오는 메시지와 해결

10. FAQ

Q. 목록에 장비가 V5 scanner로 나오는데 수동 장비는 Microscope입니다. 어느 것이 쓰이나요? A. 해상도가 V5 원본 크기와 정확히 같으면 그 이미지에는 V5 scanner가 쓰입니다(파랑 표시). 수동 장비는 크기를 알 수 없는 이미지에만 쓰입니다. 무조건 수동 장비를 쓰려면 [모든 이미지에 수동 장비 강제]를 켜세요.

Q. 배율도 자동으로 알 수 있나요? A. 아니요. 해상도로는 배율을 알 수 없으므로 [배율]은 항상 직접 고른 값이 모든 이미지에 적용됩니다. 배율이 다른 이미지는 나누어 실행하세요.

Q. 이전 버전(1.4.t2)과 결과가 다릅니다. A. (1) 1.4.t2는 감지한 장비를 쓰지 않고 콤보박스 장비로만 처리했습니다. 1.5.0은 원본 크기 이미지에 감지 장비를 씁니다. (2) JPG는 품질이 75 → 95로 높아져 파일이 커지고 픽셀 값이 약간 다릅니다. 같은 장비·같은 설정의 PNG/TIF/BMP 결과는 1.4.t2와 픽셀 단위로 같도록 만들었습니다(개발 시험 환경에서 확인, Windows 실제 확인은 수용 시험 항목).

Q. 스케일 크기에 12.5를 넣었는데 라벨이 12µm입니다. A. 이전 버전과 같은 규칙으로 라벨·파일명에는 정수 부분만 씁니다(막대는 12.5 µm로 정확히 계산). 정수 µm 사용을 권장합니다.

Q. 결과를 원본 폴더에 저장해도 되나요? A. 됩니다. [변경…]으로 원본 폴더를 고르면 결과가 새 이름으로 저장되며, 원본은 덮어쓰지 않습니다.

Q. 관리자 권한으로 실행해야 하나요? A. 아니요. 프로그램 폴더에 쓸 수 없으면 다른 폴더를 고르게 합니다.

Q. 이미지가 많으면 메모리가 걱정됩니다. A. 미리보기는 선택한 한 장의 축소본만 보관하고, 처리는 한 장씩 읽고 저장한 뒤 바로 해제합니다. 다만 목록에 추가할 때 크기 확인을 위해 이미지를 한 번씩 읽으므로 추가에 시간이 걸릴 수 있습니다(상태줄에 진행 표시).

Q. 스케일바만 따로 그린 그림이 필요합니다. A. 미리보기의 "스케일바만"은 확인용 화면입니다. 파일로 저장하는 기능은 없습니다.

11. 이전 버전 사용자를 위한 변경 요약

12. 버전·문의

• 버전 1.5.0 · 개발: 이용관
• 오류 기록: %LOCALAPPDATA%\ScalebarGUI_YK\error_log.txt
• 이 설명서의 화면 설명은 Linux 시험 환경 기준으로 작성되었습니다. Windows에서 글꼴·크기가 조금 다를 수 있습니다.

이미지 격자 합치기 1.1.0 사용설명서

1. 이 프로그램은 무엇인가요?

여러 장의 이미지를 열 × 행 격자(예: 3 × 2 = 6칸)에 차례로 배치해 한 장의 이미지 파일로 저장하는 Windows 프로그램입니다.

• 조건별·시료별 사진, 현미경 이미지, 처리 전후 비교 이미지 등을 한 장으로 모아 보고서·발표 자료·기록에 넣을 때 씁니다.
• 원본 이미지는 읽기만 하며 절대 바꾸지 않습니다. 결과는 사용자가 지정한 새 파일로 저장됩니다.
• 격자는 1 × 1부터 10 × 10(최대 100칸)까지 만들 수 있습니다.
• 입력 형식: JPG(.jpg, .jpeg), PNG, BMP, GIF, TIF(.tif, .tiff)
• 저장 형식: PNG(.png), JPG(.jpg), BMP(.bmp), TIFF(.tif)
• 휴대폰·카메라 사진의 EXIF 회전 정보를 읽어 올바른 방향으로 세워서 사용합니다.

2. 실행하기

1. 프로그램 폴더에 다음 네 파일이 함께 있는지 확인합니다. run_image_grid_combiner.cmd, image_grid_combiner.ps1, GridCombiner.Core.psm1, GridCombiner.Imaging.psm1
2. run_image_grid_combiner.cmd를 더블 클릭합니다.
3. 잠시 후 "이미지 격자 합치기 1.1.0 - 3 x 2" 창이 화면 가운데에 열립니다. 검은 PowerShell 창은 보이지 않는 것이 정상입니다.

실행 정책 안내 — .cmd는 powershell.exe -ExecutionPolicy Bypass ...로 실행합니다. 이 설정은 이번에 여는 PowerShell 프로세스 하나에만 적용되며, 컴퓨터의 실행 정책(Get-ExecutionPolicy)은 바꾸지 않습니다. 관리자 권한도 필요 없습니다. 회사 보안 정책(그룹 정책)이 스크립트 실행 자체를 막는 PC에서는 열리지 않을 수 있으니 IT 담당자에게 문의하세요.

3. 화면 구성

┌──────────────────────────────────────────────────────────────────────┐
│ 3 x 2 이미지 합치기                                            4 / 6 │  ← ① 제목 / 채움 표시
├──────────────────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                               │
│ │ 미리보기 │ │ 미리보기 │ │          │                               │
│ │1. a.jpg  │ │2. b.png  │ │    3     │                               │  ← ② 칸 격자
│ └──────────┘ └──────────┘ └──────────┘                               │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                               │
│ │ 미리보기 │ │ 미리보기 │ │          │                               │
│ │4. d.tif  │ │5. e.gif  │ │    6     │                               │
│ └──────────┘ └──────────┘ └──────────┘                               │
├──────────────────────────────────────────────────────────────────────┤
│ 열 [3] 행 [2] [격자 적용] [이미지 선택] [초기화]  배치 [맞춤 ▼]         │  ← ③ 조작 1줄
│ 결과 크기 [자동 ▼] 너비 [3000] 높이 [2000] 확장자 [PNG ▼] [합치기 저장] │  ← ④ 조작 2줄
│ 이미지 5개를 넣었습니다.   ※ 미리보기는 맞춤 기준입니다. 저장 결과는 … │  ← ⑤ 안내/상태 줄
└──────────────────────────────────────────────────────────────────────┘

버튼과 목록 위에 마우스를 잠시 올리면 짧은 설명(도움말 풍선)이 나옵니다.

4. 칸 번호와 순서

칸 번호는 왼쪽 위에서 시작해 오른쪽으로, 줄이 끝나면 다음 줄로 이어집니다(행 우선).

3 x 2 격자            2 x 3 격자
┌───┬───┬───┐        ┌───┬───┐
│ 1 │ 2 │ 3 │        │ 1 │ 2 │
├───┼───┼───┤        ├───┼───┤
│ 4 │ 5 │ 6 │        │ 3 │ 4 │
└───┴───┴───┘        ├───┼───┤
                     │ 5 │ 6 │
                     └───┴───┘

저장된 결과 이미지도 같은 순서로 배치됩니다.

5. 단계별 사용법

5.1 격자 설정

1. 아래쪽 열과 행 숫자를 정합니다(각 1~10). 예: 가로 4장 × 세로 2줄이면 열 4, 행 2.
2. [격자 적용]을 누릅니다. 칸이 다시 만들어지고 제목이 4 x 2 이미지 합치기로 바뀝니다.
3. 이미 넣어 둔 이미지는 1번 칸부터 번호 그대로 새 격자로 옮겨집니다. 칸 수가 줄면 뒤쪽 번호의 이미지는 빠집니다. (예: 6칸 → 4칸이면 5·6번 이미지는 빠지고, 다시 넣어야 합니다.)

5.2 이미지 넣기

세 가지 방법이 있습니다.

(가) [이미지 선택] 버튼 1. [이미지 선택]을 누릅니다. 2. 파일 선택 창에서 이미지를 하나 또는 여러 개 고릅니다(Ctrl/Shift + 클릭). 3. [열기]를 누르면 선택한 파일이 비어 있는 칸에만 번호 순서대로 들어갑니다. 이미 이미지가 있는 칸은 바뀌지 않습니다. 4. 빈 칸보다 파일이 많으면 남는 파일은 넣지 않고, 몇 개를 넣지 못했는지 알려 줍니다.

(나) 격자 바탕에 끌어다 놓기 (특정 칸 지정 없음) - 탐색기에서 파일을 끌어 격자 영역의 칸 바깥 회색 여백(칸과 칸 사이, 격자 가장자리)에 놓으면 (가)와 똑같이 빈 칸에만 순서대로 들어갑니다. - 위쪽 제목 영역과 아래쪽 버튼 영역은 끌어다 놓는 곳이 아닙니다(마우스 모양이 금지 표시로 바뀝니다).

(다) 특정 칸 위에 끌어다 놓기 (칸 지정) - 파일을 원하는 칸(미리보기 또는 번호 글자) 위에 놓으면 그 칸부터 차례로 들어갑니다. - 이 방식은 1.0과 같습니다: 그 칸과 뒤따르는 칸에 이미 이미지가 있어도 바꿔 넣습니다(덮어쓰기). 마지막 칸을 넘으면 첫 번째 빈 칸부터 이어서 넣고, 빈 칸도 없으면 "칸이 모두 찼습니다" 안내 후 멈춥니다. - 이미지 한 장을 다른 이미지로 바꾸고 싶을 때 가장 편한 방법입니다.

참고 - 지원하지 않는 형식(예: .webp, .heic, .txt)은 건너뛰고, 상태 줄에 건너뛴 개수를 알려 줍니다. 끌어다 놓은 파일이 모두 지원하지 않는 형식이면 "지원하는 이미지 파일을 끌어다 놓아주세요." 안내가 나옵니다. - 손상되었거나 열 수 없는 이미지는 "이미지를 열 수 없습니다." 안내와 함께 건너뜁니다. - 칸을 비우려면 [초기화]로 전체를 비운 뒤 다시 넣습니다(칸 하나만 비우는 기능은 없습니다).

5.3 배치 방식 고르기 (맞춤 / 채우기)

배치 목록에서 고릅니다. 자세한 차이는 6장을 보세요. - 맞춤: 이미지 전체가 보이도록 칸 안에 넣습니다. 남는 곳은 흰색 여백입니다. - 채우기: 칸을 빈틈없이 채웁니다. 칸 밖으로 넘치는 부분은 잘립니다.

칸의 미리보기는 항상 맞춤 방식으로 보입니다. 채우기를 골라도 미리보기는 바뀌지 않으며, 실제 저장 결과는 선택한 배치와 결과 크기를 따릅니다.

5.4 결과 크기 정하기

결과 크기 목록에서 고릅니다.

• 자동: 너비 = (가장 넓은 이미지의 너비) × 열 수, 높이 = (가장 높은 이미지의 높이) × 행 수
• 예: 3 × 2 격자에 400×300, 300×400, 1920×1080 … 이미지가 있으면 1920 × 3 = 5760, 1080 × 2 = 2160 → 5760 × 2160 픽셀
• 사진 방향(EXIF)을 적용한 뒤의 크기로 계산합니다. 세로로 찍은 4000×3000 사진은 3000×4000으로 계산됩니다.
• 원본 해상도를 최대한 살리지만 결과가 매우 커질 수 있습니다(8장 참고).
• 직접 입력: 너비·높이를 픽셀로 입력합니다.
• 범위 1~30000, 기본값 3000 × 2000
• 너비는 열 수 이상, 높이는 행 수 이상이어야 합니다. 아니면 "직접 입력 크기는 열/행 수보다 커야 합니다." 안내가 나옵니다.
• 전체 크기를 칸 수로 나누어 칸 크기를 정합니다. 나누어떨어지지 않으면 칸마다 1픽셀 정도 차이가 날 수 있지만 칸 사이에 빈틈은 생기지 않습니다.

5.5 저장 형식(확장자) 고르기

결과 이미지는 흰 바탕의 24비트 RGB 색상으로 저장됩니다(투명 영역은 흰색이 됩니다).

5.6 저장하기

1. 모든 칸에 이미지를 넣으면 [합치기 저장] 버튼이 눌러집니다. (칸이 비어 있으면 "이미지 6개를 모두 넣은 뒤 저장하세요." 안내)
2. 버튼을 누르면 먼저 이미지 크기를 확인합니다(상태 줄: "이미지 크기를 확인하는 중입니다...").
3. 결과가 매우 크면 확인 창이 나옵니다(8장 참고).
4. 저장 창이 열립니다. 기본 파일 이름은 combined_<열>x<행>.<확장자>(예: combined_3x2.png)입니다. 폴더와 이름을 정하고 [저장]을 누릅니다. - 같은 이름의 파일이 있으면 Windows 저장 창이 덮어쓸지 묻습니다. - 파일 이름의 확장자가 선택한 형식과 다르면 형식에 맞게 자동으로 바뀝니다(예: JPG 선택 + 결과.jpeg 입력 → 결과.jpg). 바뀐 이름의 파일이 이미 있으면 "같은 이름의 파일이 이미 있습니다. 덮어쓸까요?"를 한 번 더 묻습니다.
5. 저장하는 동안 마우스 커서가 모래시계로 바뀌고 상태 줄에 "저장하는 중입니다..."가 보입니다.
6. 끝나면 "저장했습니다." 창과 함께 저장 경로가 표시됩니다.

저장 방식(1.1.0) - 결과를 먼저 같은 폴더의 임시 파일(~igc_xxxxxxxxxxxx.tmp)에 저장한 뒤, 완성되면 최종 이름으로 바꿉니다. 저장 도중 오류가 나도 기존 파일은 그대로 남습니다. 임시 파일은 자동으로 지워집니다. - 이미지를 한 장씩 불러와 그리고 바로 해제하므로 1.0보다 메모리를 훨씬 적게 씁니다. 결과 픽셀은 1.0과 같습니다.

6. 맞춤과 채우기의 차이

가로로 긴 사진(4000 × 3000)을 정사각형 칸(1000 × 1000)에 넣는 예입니다.

맞춤 — 축소 비율 = min(칸 너비 / 이미지 너비, 칸 높이 / 이미지 높이) = min(0.25, 0.333) = 0.25 → 1000 × 750 크기로 그리고, 위아래에 125픽셀씩 흰 여백이 생깁니다. 이미지가 잘리지 않습니다.

┌────────────────────┐
│░░░░░░ 흰 여백 ░░░░░│  125px
├────────────────────┤
│                    │
│   사진 전체 보임    │  750px
│                    │
├────────────────────┤
│░░░░░░ 흰 여백 ░░░░░│  125px
└────────────────────┘
       1000px

채우기 — 확대 비율 = max(0.25, 0.333) = 0.333 → 1333 × 1000 크기로 그리고 칸 가운데에 맞춘 뒤, 칸 밖으로 나간 왼쪽·오른쪽 약 167픽셀씩은 잘립니다. 여백이 없습니다.

   잘림 ┊                    ┊ 잘림
  ░░░░░░┌────────────────────┐░░░░░░
  ░░░░░░│                    │░░░░░░
  ░░░░░░│   칸을 가득 채움    │░░░░░░   1000px
  ░░░░░░│                    │░░░░░░
  ░░░░░░└────────────────────┘░░░░░░
   167px       1000px          167px

• 이미지와 칸의 가로·세로 비율이 같으면 맞춤과 채우기 결과가 같습니다.
• 작은 이미지는 칸 크기에 맞게 확대됩니다(두 방식 모두). 고품질 보간(HighQualityBicubic)을 씁니다.
• 채우기는 사진의 가장자리(눈금자, 라벨 등)가 잘릴 수 있으니 저장 후 확인하세요.

7. 파일 이름과 저장 위치

8. 큰 이미지와 메모리

결과 이미지 한 장을 만들려면 가로 × 세로 × 3바이트 정도의 메모리가 필요합니다.

• 1.5 GB를 넘거나 가로·세로가 65,000픽셀을 넘으면 "결과 이미지가 매우 큽니다 … 계속 저장할까요?" 창이 나옵니다. [예]를 누르면 저장을 시도합니다.
• 약 2 GB를 넘으면 Windows 이미지 처리(GDI+)가 만들 수 없는 크기이므로 저장하지 않고 이유를 알려 줍니다.
• 1.0은 저장할 때 모든 입력 이미지를 원본 해상도로 동시에 메모리에 올렸습니다(예: 4032×3024 사진 6장이면 이미지만 약 280 MB). 1.1.0은 한 번에 한 장만 올리므로 필요한 메모리가 "결과 이미지 + 가장 큰 입력 한 장" 정도로 줄었습니다.

큰 결과를 피하는 방법 - 결과 크기 → 직접 입력으로 바꿔 필요한 크기(예: 발표용 3000 × 2000, 인쇄용 6000 × 4000)를 지정합니다. - 칸 수가 많으면 격자를 나눠 두세 장으로 저장합니다. - 메모리가 부족한 PC에서는 다른 프로그램을 닫고 저장합니다.

9. 원본 보존과 안전

• 원본 이미지 파일은 열어서 읽기만 하고 절대 수정·이동·삭제하지 않습니다.
• 결과 파일은 사용자가 저장 창에서 확인한 이름으로만 저장합니다. 덮어쓰기 전에는 반드시 묻습니다.
• 결과를 원본과 같은 이름으로 저장하면 원본이 결과로 바뀝니다. 원본 폴더와 다른 곳에 저장하는 것을 권장합니다.
• 저장이 끝나기 전에 오류가 나면 기존 파일은 바뀌지 않습니다(임시 파일 후 교체 방식).

10. 오류 메시지와 해결 방법

오류 기록 파일 여는 법: Windows 키 + R → %LOCALAPPDATA%\ImageGridCombiner 입력 → Enter → error.log를 메모장으로 엽니다.

11. 자주 묻는 질문

Q. 미리보기에서는 여백이 있는데 채우기로 저장하면 잘려 있어요. A. 정상입니다. 칸 미리보기는 항상 맞춤 방식으로 이미지 전체를 보여 줍니다. 실제 저장은 선택한 배치(맞춤/채우기)와 결과 크기를 따릅니다. 화면 아래 오른쪽의 안내 문구를 참고하세요.

Q. 이미 넣은 칸 하나만 다른 이미지로 바꾸고 싶어요. A. 새 파일을 그 칸 위에 직접 끌어다 놓으면 바뀝니다. [이미지 선택]이나 창 바탕에 놓는 방식은 빈 칸에만 들어가므로 바뀌지 않습니다.

Q. 1.0에서는 창에 끌어다 놓으면 채워진 칸도 바뀌었는데요? A. 1.1.0부터 칸을 지정하지 않은 드롭과 [이미지 선택]은 빈 칸만 채웁니다. 이미 넣은 이미지가 실수로 바뀌는 것을 막기 위한 변경입니다. 바꾸려면 칸 위에 놓으세요.

Q. 세로로 찍은 휴대폰 사진이 옆으로 누워서 나와요. A. 사진의 EXIF 회전 정보(방향 2~8)를 읽어 바로 세웁니다. 그래도 누워 있다면 사진에 회전 정보가 없는 경우이니, 사진 뷰어에서 회전해 저장한 뒤 넣으세요.

Q. 이미지 순서를 바꾸고 싶어요. A. 칸 끌어서 옮기기 기능은 없습니다. [초기화] 후 원하는 순서대로 칸 위에 하나씩 놓거나, 파일 이름 순서를 정리해 [이미지 선택]으로 한꺼번에 넣으세요.

Q. 결과가 흐릿해요. A. 결과 크기가 작으면 이미지가 축소됩니다. 자동을 쓰거나 직접 입력 크기를 키우세요. JPG 대신 PNG/TIFF를 쓰면 압축 손실이 없습니다.

Q. JPG 품질을 바꿀 수 있나요? A. 현재는 Windows 기본 품질로 저장합니다(1.0과 같음). 품질이 중요하면 PNG 또는 TIFF를 쓰세요.

Q. 투명한 PNG를 넣으면 배경이 흰색이 돼요. A. 결과는 흰 바탕 24비트 RGB로 저장되므로 투명한 부분은 흰색이 됩니다.

Q. 저장한 폴더에 ~igc_….tmp 파일이 남아 있어요. A. 저장 도중 프로그램이 강제로 종료된 경우입니다. 지워도 됩니다.

Q. 인터넷이 필요한가요? 설치가 필요한가요? A. 둘 다 필요 없습니다. Windows에 기본으로 들어 있는 PowerShell 5.1만 사용합니다.

12. 1.0과 달라진 점 (요약)