Turn phone photos of documents and boards into clean, scanner-quality images — from the command line, a browser UI, or as a Python library. It auto-detects the page, fixes perspective and orientation, removes shadows/glare, and (for colour/photo subjects) offers a few looks to pick from. Optional deep-learning backends (DocAligner detection, DocRes restoration) plug in when installed.
python3 scan.py opens the web UI; python3 scan.py in.jpg runs the CLI.
Full documentation below is in Korean.
휴대폰으로 찍은 사진을 전문 스캐너로 스캔한 것처럼 만드는 CLI + 파이썬 라이브러리. 비스듬히 찍힌 문서·보드를 정면으로 펴고(원근 보정), 글자 방향을 인식해 똑바로 세우고, 조명 얼룩·그림자를 지운 뒤 화질을 다듬는다. 같은 대상을 여러 장 찍어 넣으면 정렬·합성해 노이즈·반사광이 제거된 더 깨끗한 한 장을 만든다.
pip install -r requirements.txt # 핵심 + Sauvola/PDF/deskew
brew install tesseract # 자동 방향 감지 (선택)
pip install pytesseract # "
pip install page-dewarp # 곡면/책 페이지 펴기 (선택)
pip install docaligner-docsaid # 딥러닝 코너 검출 (선택)
# DocRes(통합 SOTA)는 PyPI에 없음 → 아래 "DocRes 엔진" 참고브라우저에서 드래그&드롭 업로드 → 옵션 선택 → 결과 미리보기 → PNG/PDF 다운로드.
그냥 인자 없이 실행하면 웹이 뜬다 — 빈 포트를 자동으로 잡고 브라우저까지 연다.
또는 Finder에서 scan.command 더블클릭(타이핑 0).
python3 scan.py # 이거면 끝 → http://127.0.0.1:8000 자동 오픈
python3 scan.py serve --port 8080 --no-browser # 포트 지정 / 브라우저 안 열기포트가 사용 중이면 자동으로 다음 빈 포트(8001, 8002…)를 쓴다.
- 기본은 최소 화면 — 업로드 → (콘텐츠 종류 auto 기본) → 스캔. 나머지 옵션은 "고급 설정" 안에 접혀 있어 부담이 없다.
- 라이트(화이트) 디자인, 우측 상단 EN / 한국어 전환(브라우저 언어 자동 감지, 선택 저장)
- 각 옵션마다 설명 문구를 함께 표시
- 조명 보정·채도 슬라이더로 컬러/포토 결과를 실시간 취향 조정
- 기본은 밸런스 단일 결과(빠름) — 딸깍 한 번이면 한 장. 고급에서 "3가지 버전 비교"를 켜면 내추럴/밸런스/비비드를 만들어 고를 수 있다(약 3배 느림)
- 회전 + 크롭 편집 — 사진을 한 장 올리면 미리보기에서 ↺↻ 회전하고 드래그로 영역을 선택해 그 부분만 스캔할 수 있다
- 작은 파일 크기 — 결과는 내용에 맞춰 자동 인코딩: 흑백 문서는 PNG(수십 KB), 컬러·사진은 JPEG(무손실 PNG 대비 약 1/6 크기)
- 진행 표시 — 처리 중 애니메이션 진행바 + 경과 시간(초)로 멈춘 게 아님을 표시
- 원본 ↔ 결과 토글 — 각 결과 카드에서 원본과 결과를 바꿔 보며 무엇이 달라졌는지 확인
- 실시간 재보정 — 단일 결과에서 조명/채도 슬라이더를 움직이면 재업로드·재검출 없이 후보정만 즉시 다시 돌려(캐시된 전처리 재사용) 결과가 바로 갱신됨
- 더 똑똑한 auto 판별 — 밝기·채도에 더해 글자 밀도·흰 종이 비율·컬러 픽셀 비율로 문서/컬러문서/사진을 구분 (회색 물체 사진을 흑백 문서로 오판하지 않음)
- 설치된 백엔드(DocAligner·dewarp·DocRes)에 해당하는 옵션만 자동 노출
터미널에서 메뉴로 답하고 싶으면 -i. 마지막에 동등한 명령어까지 보여준다(복사해 재사용).
python3 scan.py -i? Input image, folder, or glob: board.jpg
? Content type
* 1. document 2. color 3. photo 4. auto
? Remove glare / specular highlights? [y/N]: y
Equivalent command:
scan.py board.jpg -m photo --deglare -o board_scanned.png
? Run it now? [Y/n]:
python3 scan.py 사진.jpg # 자동 감지 + 흑백 문서 스캔
python3 scan.py a.jpg b.jpg c.jpg -o out.png # 여러 장 합성 → 한 장
python3 scan.py 사진.jpg -m color # 컬러 유지
python3 scan.py board.jpg -m photo # 메인보드: 사진 품질 유지
python3 scan.py 사진.jpg -m auto # 대상 보고 모드 자동 선택
python3 scan.py 사진.jpg --binarize sauvola # 흐린/얇은 글씨에 더 강한 이진화
python3 scan.py 책.jpg --dewarp # 휜 페이지 평탄화
python3 scan.py board.jpg -m photo --deglare # 광택 반사광(glare) 제거
python3 scan.py 사진.jpg --detector docaligner # 딥러닝 코너 검출
python3 scan.py 사진.jpg --engine docres --docres-task appearance # DocRes SOTA
python3 scan.py 사진.jpg --pdf -o out.pdf # PDF로 저장
python3 scan.py scans/ --pdf -o book.pdf # 폴더 전체 → 다중페이지 PDF
python3 scan.py scans/ --batch -o outdir # 폴더 전체 → 장당 파일 하나씩여러 이미지를 넣으면 기본적으로 한 대상의 여러 컷 → 합성으로 처리한다.
각각을 별개 문서로 다루려면 --batch(또는 폴더 입력)를 쓴다.
| 모드 | 용도 | 처리 |
|---|---|---|
document (기본) |
A4 보고서·문서 | 그림자 제거 → 고대비 흑백 |
color |
컬러 문서·영수증 | 조명 평탄화 → 대비·채도 보정 |
photo |
메인보드·부품·물체 | 컬러 유지, 조명 균일화 + 선명도 |
auto |
아무거나 | 밝기·채도로 위 셋 중 자동 선택 |
-o/--output,-m/--mode,--binarize {adaptive,sauvola}--detector {auto,contour,docaligner}: 문서 검출 백엔드 (auto=설치돼 있으면 딥러닝)--deglare: 단일샷 반사광(스페큘러) inpaint 제거 — 광택 보드/코팅지--dewarp: 곡면/책 페이지 평탄화 (page-dewarp 필요, 옵트인, 컬러 보존)--gain S: 조명 보정 강도 0~1 (컬러/포토, 기본 0.7)--saturation M: 채도 배율 (컬러/포토, 1.0=그대로, 기본 1.05)--engine {classic,docres}+--docres-task {...}: 통합 DL 복원 엔진--pdf,--batch--no-crop/--no-deskew/--no-auto-rotate--rotate {90,180,270}: 수동 회전--sharpness RATIO: 합성 시 흔들린 프레임 제외 기준 (기본 0.6)--no-refine: 합성 ECC 서브픽셀 미세정렬 끄기--orient-conf C: 자동 회전 신뢰 임계값 (기본 1.0)--debug: 단계별 진단 출력
- 검출: 기본은
contour(순수 CV, 3중 후보맵).docaligner-docsaid설치 시auto가 딥러닝 히트맵 코너 검출을 먼저 쓰고 실패하면 컨투어로 폴백. 딥러닝 쪽이 어둡고 어수선한 실제 배경에서 강함(합성 이미지엔 약할 수 있음). - 반사광:
--deglare는 밝고 채도 낮은 스페큘러 픽셀을 마스킹해cv2.inpaint. 작은/중간 blob에 효과적, 대상의 큰 면적을 덮는 반사광은 안전상 건너뜀. - deskew:
deskew(Radon) 라이브러리가 있으면 자동 사용(Hough보다 정밀), 없으면 Hough.
DocRes (CVPR 2024)는 dewarping·deshadowing·
appearance·deblurring·binarization을 한 모델로 처리하는 SOTA. PyPI에 없어 어댑터로
연결한다 — 아래를 갖추면 --engine docres가 즉시 동작하고, 없으면 클래식으로 폴백한다.
git clone https://github.com/ZZZHANG-jx/DocRes
# OneDrive에서 가중치 받기: docres.pkl → DocRes/checkpoints/,
# mbd.pkl → DocRes/data/MBD/checkpoint/
pip install torch torchvision # + DocRes/requirements.txt
export DOCRES_DIR=/path/to/DocRes
python3 scan.py in.jpg --engine docres --docres-task end2end어댑터는 DocRes의 inference.py를 subprocess로 호출하므로 모델 코드를 vendoring하지
않는다(버전 충돌 회피).
from scanlib import ScanConfig, scan_images
result = scan_images(["a.jpg", "b.jpg"], ScanConfig(mode="document",
binarize="sauvola"))합성(여러 장) → 문서 검출+원근보정 → dewarp(선택) → 미세 기울기 보정
→ 후보정(모드별) → 방향 자동 정렬
- 품질 필터 + 합성 (
scanlib/merge.py) — 흔들린/초점 나간 프레임을 선명도로 걸러내고, 가장 선명한 장 기준으로 ORB 매칭 + ECC 서브픽셀 정렬 후 픽셀별 중앙값 합성. 매 장 다른 반사광·손그림자·노이즈가 제거된다. - 견고한 문서 검출 (
scanlib/detect.py) — Canny 엣지 + Otsu + 넓은 창 적응형 이진화, 세 후보 맵에서 사각형을 모아 면적·직사각형도로 채점. 어두운/무늬 배경에서도 검출. 신뢰도가 낮으면 크롭을 건너뛰고 원본 유지. - 원근 보정 + 미세 기울기 보정 (
scanlib/geometry.py) — 4점 워프로 정면화한 뒤, 허프 직선으로 잔여 기울기(±몇 도)를 추가 보정. - 곡면 dewarping (
scanlib/dewarp.py, 선택) — cubic-sheet 모델(page-dewarp)로 휜 페이지를 평탄화. 촬영된 텍스트 페이지에 맞춰져 있어 옵트인이며, 부적합한 입력에선 원본으로 안전 폴백. - 후보정 (
scanlib/enhance.py) — 해상도 비례 커널로 그림자 제거, 모드별 대비/ 채도/선명도. 이진화는 adaptive(빠름) 또는 Sauvola(저대비·얇은 글씨에 강함). - 방향 정렬 (
scanlib/orient.py) — Tesseract OSD로 글자 방향을 읽어 회전. 확신도가 임계값 미만이면 오판 방지를 위해 회전하지 않는다.
scan.py # 얇은 CLI 진입점
scanlib/
detect.py # 문서 검출 (컨투어 3중맵 + DocAligner 딥러닝 백엔드)
geometry.py # 코너 정렬·워프·미세 기울기 보정 (deskew 라이브러리)
merge.py # 다중 프레임 품질필터·정렬·합성 (ORB+ECC)
glare.py # 단일샷 반사광 inpaint 제거
orient.py # 방향 자동 정렬
enhance.py # 후보정 (adaptive/Sauvola, 해상도 비례)
dewarp.py # 곡면 페이지 평탄화 (page-dewarp, 선택)
docres.py # DocRes 통합 DL 복원 어댑터 (선택)
pipeline.py # ScanConfig + 오케스트레이션 (라이브러리 API)
output.py # PNG/PDF 인코딩 (CLI·웹 공용)
cli.py # argparse + serve 명령
wizard.py # 대화형 메뉴 (GUI처럼, 인자 없이 실행 시)
webapp.py # Flask 웹 UI (업로드·미리보기·다운로드)
tests/test_scan.py # pytest (29 케이스)
pytest -q- 합성은 정렬 정확도에 의존한다. 글자·텍스처가 풍부할수록 정확하고, 빈 여백이 크거나 반복 패턴만 있으면 겹침이 생길 수 있다.
- dewarping은 cubic-sheet(page-dewarp) 기반이라 촬영된 텍스트 페이지에 최적. 심한 왜곡·비정형 문서는 딥러닝 rectifier(DocScanner, DocTr)가 더 낫지만 PyTorch·사전학습 모델이 필요해 여기선 채택하지 않았다 (향후 옵션).
- 검출을 더 끌어올리려면 딥러닝 세그멘테이션(MIDV-500 학습) 경로를 추가할 수 있다.