☘ HWPX CLOVIS 사용자 매뉴얼

1제품 개요

HWPX CLOVIS(마스코트 클로비스)는 손글씨·스캔이 섞인 수학 문제지 PDF나 이미지를 받아, 글자와 수식을 정확히 판독하고 풀이·해설까지 붙여 아래아한글에서 그대로 편집할 수 있는 .hwpx 시험지로 자동 생성하는 프로그램입니다.

핵심 처리 단계는 다음과 같습니다.

2준비물과 전제조건

3설치와 실행

HWPX CLOVIS는 전용 파이썬 런타임까지 함께 들어 있는 자기완결 설치본입니다. 별도 설치 과정이 없습니다.

1. 받은 HWPX CLOVIS 폴더를 원하는 위치에 둡니다. (예: C:\HWPX CLOVIS)
2. 폴더 안의 run_hwpx_clovis.bat 파일을 더블클릭합니다.
3. 잠시 후 네온 테마의 검은 창이 뜨면 실행에 성공한 것입니다.

폴더 구조 (참고)

4최초 설정 — API 키와 저장 폴더

프로그램을 처음 켜면 두 가지를 먼저 지정해야 작업을 시작할 수 있습니다.

1. 오른쪽 위 점 세 개(⋮) 메뉴 → 설정…을 엽니다.
2. ① API 사용자 관리에서 「API 키 불러오기」를 누르고, 본인 Gemini 키를 입력합니다. 한 번 등록하면 암호화되어(users.enc) 저장되므로 다음부터는 ID·비밀번호로 불러옵니다.
3. ② 작업 저장 폴더에서 결과 .hwpx가 저장될 폴더를 지정합니다. (기본값 C:/Autohwp/workspace)
4. 저장을 눌러 설정창을 닫습니다.

5설정창 상세 — ① ~ ⑤

③ 동작 옵션 — 동시 호출 수와 역할별 모델

• 동시 호출 N — 문제를 한꺼번에 몇 개씩 AI로 보낼지(병렬 처리)입니다. 기본 8, 최대 30. 실제로는 안전을 위해 작업 수의 절반이 자동 상한이 됩니다.
• 역할별 모델 — 작업 성격에 맞춰 서로 다른 AI 모델을 고를 수 있습니다.

  역할	용도
  크롭·검출	영역·문제 검출 단계
  OCR·수식	글자·수식 판독, 풀이 생성 (품질 핵심)
  이미지개선	도형 개선용 이미지 모델

  각 드롭다운에는 (추천)과 과금 라벨이 함께 표시되어 비용을 가늠할 수 있습니다.

6기본 작업 흐름 한눈에

1. PDF·이미지 불러오기 — 메인 화면에서 자료를 엽니다.
2. 크롭 창에서 문제 영역 지정 — 문제 하나하나에 네모 박스를 그립니다. (1박스 = 1문제)
3. 작업 버튼 선택 — OCR / 해설 / 변형 등 원하는 버튼을 누릅니다.
4. 작업 설정 다이얼로그 확인 — 안내문과 옵션(미주·원본삽입·2차검수·도형개선)을 확인하고 Enter로 실행합니다.
5. 병렬 처리 진행 — 여러 문제가 동시에 AI로 처리되며 로그에 진행 상황이 찍힙니다.
6. 완료 — 저장 폴더에 .hwpx가 생성됩니다. 아래아한글로 열어 확인합니다.

7크롭(자르기) 창 사용법

크롭 창은 여러 페이지(이미지·PDF)를 하나로 합쳐 넘겨 보며 문제 영역을 지정하는 작업 공간입니다.

1. 박스 그리기 — 문제 한 개를 감싸도록 드래그해 네모를 만듭니다.
2. 읽기 순서 자동 배지 — 박스를 만들면 번호 배지가 붙습니다. 번호는 2단(컬럼) 읽기 순서 (왼쪽 위 → 왼쪽 아래 → 오른쪽 위 → 오른쪽 아래)로 자동 정렬됩니다.
3. 페이지 이동·패닝 — 마우스 휠과 화살표 키로 화면을 이동합니다.
4. 박스 미세 이동 — Ctrl + 화살표로 선택한 박스를 한 칸씩 옮깁니다.
5. 선택/해제 — 선택한 박스만 누적 번호가 매겨지고, 토글·이동 시 번호가 자동 갱신됩니다.

8작업 버튼 6종

왼쪽은 변형 문제 생성, 오른쪽은 판독·해설 작업입니다. 각 버튼은 누르면 안내 다이얼로그가 먼저 뜹니다.

9옵션 4종 상세

2차 검수가 품질을 올리는 원리

1단계에서 OCR만 수행해 깨끗한 문제 본문을 확보한 뒤, 2단계 해설은 그 깨끗한 텍스트를 권위 있는 입력으로 받습니다 (원본 이미지는 도형 참고용으로만 사용). 한 번에 판독·해설을 동시에 시키는 단일 처리의 부하와 오독 전파를 제거하므로, 지저분한 고난도 문제에서 특히 정확합니다.

10복합융합 문제 만들기

1. 크롭 창에서 묶고 싶은 문제들에 박스를 매긴 뒤 메인으로 돌아옵니다.
2. 복합융합문제 버튼을 누르면 전용 설정 패널이 펼쳐집니다.
3. 패널 상단의 빨간 경고 배너(검수 필요)를 확인합니다.
4. 필요 시 원본 삽입 옵션을 켭니다. 융합 해설은 기본적으로 본문 인라인으로 들어갑니다.
5. 실행하면 배지 번호 순서대로 묶여 하나의 융합 문제로 재구성됩니다.

11결과 확인과 후처리

1. 작업이 끝나면 저장 폴더에 .hwpx 파일이 생깁니다. (⋮ 메뉴 → 작업 저장 폴더 열기로 바로 이동)
2. 파일을 아래아한글로 엽니다. 수식은 편집 가능한 한글 수식으로 들어가 있어 그대로 수정할 수 있습니다.
3. 한글이 설치돼 있으면 열 때 수식 히트박스(클릭 영역)가 자동 보정됩니다.
4. 변형·융합·해설 결과는 사람이 검수한 뒤 사용하십시오.

12안정성 · 검토필요 폴백

대량 처리 중 일부 문제가 실패하더라도 작업 전체가 멈추지 않도록 설계되어 있습니다.

• 검토필요 폴백 — 판독에 실패하거나 시간이 초과된 문제는 버려지지 않고, 원본 이미지 + 【검토 필요】 주석으로 문서에 들어갑니다. 동시에 검토필요_목록.txt 요약 파일이 생성됩니다.
• 자동 재시도 — 일시적 한도 초과(429)는 권장 대기 시간을 읽어 자동 재시도하고, 남은 실패는 한 번 더 일괄 재처리합니다.
• 타임아웃 보호 — 한 문제가 120초를 넘기면 무한 대기 대신 곧바로 검토필요로 처리합니다.
• 중단(STOP) — 진행 중 중단해도 그때까지의 결과는 보존되어 빌드됩니다.

13서버 빌드(렌탈) 옵션 — 구독자용

구독(렌탈) 사용자는 빌드 단계를 서버에서 처리하도록 켤 수 있습니다. 기본값은 해제 = 로컬 빌드이며, 켜지 않으면 모든 동작이 기존과 동일합니다.

1. 설정창 ⑤ 서버 빌드(렌탈)에서 서버 주소·아이디·비밀번호를 입력합니다.
2. 서버 로그인을 누릅니다. 성공하면 ✓ 로그인됨이 표시됩니다.
3. 「서버에서 빌드」 체크를 켜면 이후 빌드가 서버에서 수행됩니다.

14트러블슈팅 FAQ

실행 / 설정

품질 / 처리

가장 흔한 함정 — 코드 변경 후 앱 재시작