Chika 딥다이브
— 폰이 대신 "컷을 짚어주는" 만화책 리더

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 "a panel-by-panel comic reader for Android — open a CBZ/CBR, and Chika finds the panels with an on-device ML model and guides you through them one tap at a time"다. 이름 Chika는 산스크리트/힌디어 Chitra Katha("그림 이야기")의 줄임말로, 브랜드명과 실제 코드의 패키지명(com.chakra.comicreader)이 다르다는 점이 흥미롭다 — 프로젝트 소유 조직이 Chakra(Chalchitra Krida)이고, "Chika"는 그 위에 얹은 제품/브랜드 이름이다.

겉보기엔 별 4개 리포지토리로는 소박해 보이지만(★14), 실제로는 Kotlin Multiplatform(KMP)으로 설계된 :shared 모듈, 완성도 높은 Swift 기반 iOS 앱(iosApp/), 그리고 자체 YOLO 모델 재학습 파이프라인(training/)까지 갖춘, 겉보다 훨씬 기술적으로 두꺼운 프로젝트다. 이 문서는 그 "겉보다 두꺼운" 부분 — 패널 탐지 알고리즘, 리딩 오더 계산, 병합/분할 플래너, 카메라 수학, KMP 구조 — 을 실제 소스코드 수준에서 파헤친다.

2왜 주목받는가

트렌딩 이유 · 기존 CBZ 뷰어/Tachiyomi류 대비 차별점.

만화 뷰어 앱은 이미 시장에 넘친다. Tachiyomi(및 그 포크들), Perfect Viewer, YACReader 같은 앱들은 모두 "페이지를 잘 보여주는" 데 집중해왔다. Chika가 주목받는 이유는 이 문제를 다른 방향에서 풀었기 때문이다 — "페이지를 어떻게 보여줄까"가 아니라 "컷을 어떻게 순서대로 짚어줄까"를 온디바이스 ML로 자동화했다는 점, 그리고 그 위에 처음부터 KMP(Kotlin Multiplatform)로 안드로이드·iOS 양쪽에 같은 핵심 로직을 재사용하도록 설계했다는 점이다.

기존 방식과 무엇이 다른가

또 하나 주목할 점은 라이선스 투명성이다. THIRD_PARTY_NOTICES.md는 번들된 TFLite 모델이 Manga109-s(학술 연구용 만화 데이터셋)로 학습됐다는 사실과, 이로 인해 상업적 배포 시 발생할 수 있는 라이선스 모호성(일부 해석은 CC BY-NC-SA로 봄)까지 스스로 문서화해 공개한다. 오픈소스 프로젝트가 흔히 얼버무리는 "학습 데이터 출처 문제"를 정면으로 인정하고 기록해둔 점은 신뢰도를 높이는 요소다.

3기술 스택 전체 지도

KMP 2모듈(:shared/:app) + Compose UI + 온디바이스 ML + 아카이브 처리.

4아키텍처 심화 분석

:shared(commonMain) ↔ :app(Android) 분리 + 패널 검출 5단계 파이프라인 + 리더 상태머신.

Chika의 뼈대는 "플랫폼에 안 묶이는 순수 로직"과 "플랫폼 전용 I/O"를 철저히 분리하는 것이다. shared/build.gradle.kts의 주석이 이 원칙을 명문화한다 — "commonMain에는 어떤 플랫폼(Android 등) API도 추가되어선 안 된다. TFLite/LiteRT, 비트맵 디코딩, 아카이브 백엔드 같은 플랫폼 통합은 이 인터페이스들 뒤, 즉 소비하는 타겟(:app, iosApp) 쪽에 있어야 한다"는 규칙이다.

패널 검출 파이프라인 — 픽셀에서 "다음 컷"까지 5단계

PanelPipeline.zoomRegions() 하나가 전체 후처리를 오케스트레이션한다. 실제 흐름을 단계별로 따라가보자.

① 최대 빈 직사각형 — 모델이 놓친 컷 복구하기

PanelGapFiller는 페이지를 64×64 그리드로 샘플링해 어떤 셀이 이미 패널로 덮였는지 표시한 뒤, 고전적인 "히스토그램에서 최대 직사각형 찾기" 알고리즘(스택 기반, O(n))을 행마다 반복 적용해 아직 덮이지 않은 영역 중 가장 큰 직사각형을 찾는다. 이 영역이 페이지 면적의 7% 이상이고 각 변이 12% 이상이면(얇은 여백/거터가 아니라 진짜 컷일 가능성이 높으면) 새 패널로 추가한다.

// PanelGapFiller.kt — 왜 "연결 요소"가 아니라 "최대 직사각형"을 쓰는가
// 페이지를 둘러싼 얇은 여백/거터 프레임은 모든 컷과 맞닿아 하나의 큰 "빈 영역"으로
// 연결돼 보이지만, 폭이 얇아 큰 직사각형을 이루지 못한다 → 자동으로 무시됨.
// 반면 진짜로 모델이 놓친 컷은 이웃 패널들에 둘러싸여 있어 깨끗한 직사각형으로 잡힌다.
fun fill(panels: List<Panel>, config: Config = Config()): List<Panel> {
    val rect = largestEmptyRectangle(covered, n) ?: break
    if (rect.cells * cellArea < config.minAreaFraction) break
    // 폭·높이 모두 minSideFraction 이상이어야 "진짜 컷"으로 인정, 아니면 얇은 여백으로 간주해 버림
}

② 리딩 오더 — 재귀적 X-Y 컷 + 스트래들 허용

만화는 "행(위→아래)" 단위로 읽고, 행 안에서는 읽기 방향(왼쪽→오른쪽 또는 오른쪽→왼쪽, 일본 만화는 RTL)으로 읽는다. PanelOrdering.order()는 이걸 재귀적 X-Y 컷(recursive X-Y cut)으로 계산한다 — 먼저 수평선 하나로 패널들을 위/아래 두 그룹으로 딱 나눌 수 있는지 찾고(찾으면 그게 "행 구분선"), 안 되면 수직선으로 나눠보고(열 구분선), 그마저 안 되면(테두리가 삐뚤빼뚤하거나 큰 패널이 걸쳐 있으면) "위쪽 좌표 기준으로 대충 행을 묶는" 최후 수단을 쓴다.

핵심 트릭은 STRADDLE_TOLERANCE(0.25)다 — 패널이 살짝 삐뚤어져 컷 라인을 넘어가도(자기 길이의 25% 이내라면) "더 많이 걸친 쪽"으로 배정해 억지로 한 줄에 묶는다. 반대로 진짜로 두 행에 걸친 큰 세로 패널은 수평 컷을 아예 불가능하게 만들어서, 알고리즘이 자동으로 "수직 컷 먼저"로 전환한다 — 이게 "옆에 쌓인 작은 컷들과 나란히 있는 세로로 긴 큰 컷"을 사람이 읽는 순서와 똑같이 처리하는 방법이다.

③ 병합/분할 플래너 — "읽기 좋은 크기"로 다듬기

YOLO가 찾아낸 원시 패널을 그대로 카메라 타겟으로 쓰면 너무 작은 컷(연속된 잔 컷 4~5개)이나 너무 큰 컷(스프레드, 페이지 전체 폭 패널)이 매번 튀어나와 읽기 리듬이 깨진다. PanelPlanner는 이를 두 가지 규칙으로 다듬는다.

분할 컷의 위치는 무작정 중앙이 아니라 말풍선(bubble) 그룹 사이의 가장 큰 빈틈에 놓인다 — cutPosition()이 말풍선들의 좌표 구간을 정렬해 가장 넓은 간격의 중점을 찾고, 그게 중앙 대역(30~70%) 안에 있으면 채택, 없으면 그냥 중앙으로 자른다. 말풍선 하나를 반으로 잘라버리는 어색한 분할을 피하는 실용적인 휴리스틱이다.

④ 신뢰도 게이트 — 자동화가 틀릴 것 같으면 손을 뗀다

일부 만화(특히 테두리 없는 다이내믹한 스프레드, Dandadan 같은 액션 신)는 애초에 "컷"이라는 개념이 흐릿하다. 이런 페이지에서 YOLO는 서로 심하게 겹치는 박스를 뱉어내는데, 이걸 그대로 카메라 타겟으로 쓰면 화면이 정신없이 튄다. PanelReliability.isReliable()은 패널 쌍끼리 겹치는 면적의 총합 ÷ 전체 패널 면적을 계산해, 이 값이 0.04를 넘으면(training/README.md가 "Dandadan에서 깨끗한 페이지는 ≈0.000, 혼란스러운 페이지는 ≥0.058로 실측 교정했다"고 명시) 패널 기반 자동 이동을 포기하고 전체 페이지 보기로 안전하게 폴백한다.

⑤ 리더 상태머신 — page → panel → page 슬롯 모델

ReaderViewModel은 "페이지"와 "패널"을 하나의 선형 슬롯(slot) 시퀀스로 통합한다. 슬롯 0은 페이지 전체를 보여주는 "인트로", 슬롯 1..n은 탐지된 패널들, 슬롯 n+1은 다시 페이지 전체를 보여주는 "아웃트로"다. 이 설계 덕분에 "다음"을 누르는 로직이 매우 단순해진다 — 그냥 슬롯 번호를 1 증가시키다가, 마지막 슬롯(아웃트로)을 넘어서면 다음 페이지의 슬롯 0으로 넘어간다.

// ReaderViewModel.kt — next()의 핵심 로직
fun next() {
    val lastSlot = s.panels.size + 1  // n+1 = 아웃트로 슬롯
    when {
        s.slot < lastSlot -> setSlot(s.slot + 1)                 // 슬롯만 전진
        s.pageIndex < s.pageCount - 1 -> goToPage(s.pageIndex + 1, targetSlot = 0) // 다음 페이지 인트로로
    }
}
// currentCamera: 슬롯이 1..panels.size 범위면 그 패널, 아니면 FULL_PAGE(인트로/아웃트로)
val currentCamera: Panel
    get() = if (slot in 1..panels.size) panels[slot - 1] else Panel.FULL_PAGE

패널 탐지는 지연 계산(lazy)이다 — 현재 페이지는 필요할 때 바로 탐지하고, 다음 페이지는 백그라운드로 미리 prefetch()해둔다. 탐지 결과는 panelCache: HashMap<Int, List<Panel>>에 페이지 인덱스로 캐싱돼, 뒤로 갔다 다시 오는 탐색이 재추론 없이 즉시 이뤄진다.

⑥ 카메라 수학 — contain-fit 프레이밍 + lerp 애니메이션

computePageDraw()는 "정규화된 카메라 사각형(어느 패널을 보여줄지)"을 받아 "실제 화면 픽셀 어디에, 얼마 크기로 페이지 비트맵을 그릴지"를 계산한다. 원리는 CSS의 object-fit: contain과 동일하다 — 카메라 영역이 화면에 다 보이도록(안 잘리게), 비율을 유지한 채 최대로 확대하고 중앙 정렬한다.

// CameraTransform.kt — contain-fit 스케일 계산
val scale = minOf(containerW / camW, containerH / camH) * fill  // fill=0.98, 살짝 여백
val left = containerW / 2f - camCx * scale   // 카메라 중심이 화면 중심에 오도록 평행이동
val top  = containerH / 2f - camCy * scale

패널 사이를 이동할 때는 순간 이동이 아니라 Compose의 Animatable<Panel, AnimationVector4D>로 360ms 동안 부드럽게 보간(lerp)한다. 이때 Panel이 4개의 Float(left/top/right/bottom)로 이뤄진 데이터 클래스이기 때문에, TwoWayConverter로 Panel ↔ AnimationVector4D를 정의하기만 하면 Compose 애니메이션 시스템이 "사각형 자체"를 하나의 애니메이션 가능한 값으로 다뤄준다 — 좌표 4개를 각각 따로 애니메이션시키는 것보다 훨씬 깔끔한 설계다.

여기에 사용자가 손가락으로 핀치줌/드래그한 값(userScale, userPanX/Y)이 카메라의 자동 프레이밍 위에 추가로 곱해지고 더해진다. 수평 이동은 "커버(cover)" 방식으로 clamp(좌우로 배경이 보이지 않게 제한)하고, 수직 이동은 "배경 위에 떠 있는" 방식으로 clamp(최소 15%는 화면에 남도록 허용하되 완전히 놓치지는 않게)한다 — 이 비대칭 클램핑이 "좌우 스와이프 = 페이지 넘김 제스처"와 "상하 드래그 = 자유 패닝"을 서로 헷갈리지 않게 만드는 핵심이다.

⑦ Room 영속화 — 페이지 *와* 패널 둘 다 기억하기

ComicEntity는 lastPage와 lastSlot 두 컬럼을 함께 저장한다. 단순히 "몇 페이지까지 읽었나"가 아니라 "그 페이지의 몇 번째 컷까지 읽었나"까지 정확히 복원하는 것 — 앱을 껐다 켜도 정확히 보던 컷에서 이어 읽을 수 있다. ReaderViewModel.persistProgress()가 슬롯이 바뀔 때마다(setSlot(), 페이지 전환 시) 이 값을 갱신한다.

5디렉토리 구조 해부

2개 Gradle 모듈 + iOS 앱 + 모델 학습 파이프라인.

6학습 포인트 (기술별)

이 저장소 하나로 배울 수 있는 것 + 실습 아이디어.

6-1. KMP shared/app 분리 설계 — "플랫폼 없는 코드"를 짜는 훈련

:shared의 어떤 파일도 android.*나 Bitmap 같은 플랫폼 타입을 import하지 않는다. YoloPanelDecoder.decode()는 FloatArray와 IntArray만 받고, PageLoader가 만든 실제 Bitmap은 안드로이드 쪽 MlPanelDetector가 픽셀을 뽑아 FloatArray로 변환한 뒤에야 shared 코드에 넘겨진다. 이 경계선을 지키는 습관이 "테스트 가능한 순수 함수"와 "테스트하기 어려운 I/O 코드"를 분리하는 가장 실전적인 방법이다.

6-2. YOLO 후처리 파이프라인을 직접 손으로 구현해보기

많은 튜토리얼이 YOLO를 "모델 돌리면 바로 박스가 나온다"처럼 설명하지만, 실제로는 letterbox → 좌표 역변환 → NMS → 최소 면적 필터까지 다 손으로 구현해야 한다. YoloPanelDecoder는 이 전 과정이 약 150줄 안에 압축돼 있어, YOLO 계열 모델을 온디바이스에 통합할 때 실제로 무엇을 짜야 하는지 보여주는 좋은 참고 자료다. 특히 end-to-end 출력([1,N,6])과 raw 출력([1,4+nc,anchors]) 두 레이아웃을 모두 자동 판별하는 부분은, "export한 모델의 출력 형태가 버전마다 바뀐다"는 실무의 흔한 골칫거리를 어떻게 방어적으로 처리하는지 보여준다.

// YoloPanelDecoder.kt — 두 출력 레이아웃 자동 판별
val transposed = d1 < d2  // [1, attrs, anchors] 인지 [1, anchors, attrs] 인지 shape로 추론
val endToEnd = preds <= 1000  // 예측 개수가 적으면 NMS-free end-to-end로 간주

6-3. Compose 제스처 + 캔버스 카메라 수학

ReaderScreen.kt의 pointerInput 블록은 탭 / 더블탭 / 드래그 / 핀치줌 / 스와이프 플릭 다섯 가지 제스처를 하나의 awaitEachGesture 루프 안에서 서로 충돌 없이 구분한다. 핵심은 pastSlop(터치 이동량이 "탭"과 "드래그"를 가르는 임계값을 넘었는지) 플래그와, VelocityTracker로 측정한 손가락 속도로 "천천히 끄는 드래그"와 "휙 넘기는 플릭"을 구분하는 것이다.

6-4. Room으로 "정확히 어디서 멈췄는지" 영속화하기

대부분의 읽기 앱은 "마지막 페이지"만 저장한다. Chika는 lastPage + lastSlot 두 컬럼으로 페이지 안의 몇 번째 컷까지 저장한다. ComicDao.updateProgress()가 단일 UPDATE 쿼리로 두 값과 lastOpened 타임스탬프를 원자적으로 갱신하는 패턴도 눈여겨볼 만하다.

6-5. CBZ/CBR·RAR5 아카이브 처리 — 매직 바이트로 포맷 판별

ComicFormatDetector는 파일 확장자를 신뢰하지 않는다. 대신 파일의 첫 몇 바이트(매직 넘버) — ZIP은 "PK\x03\x04", RAR은 "Rar!\x1a\x07" — 를 직접 비교해 진짜 포맷을 판별하고, 매직이 없을 때만 확장자로 폴백한다. "실제로는 RAR인데 확장자만 .cbz로 잘못 붙은 파일"이 실사용에서 흔하기 때문에 나온 방어 코드다.

6-6. LRU 비트맵 캐시 + 다운샘플 디코드로 메모리 관리하기

스캔된 만화 페이지는 종종 2000~4000px급 고해상도라, 그대로 디코딩하면 힙이 쉽게 터진다. PageLoader.decodeSampled()는 BitmapFactory.Options.inSampleSize(2의 거듭제곱 배율로 다운샘플)를 이용해 maxPageDimension(2560px) 이하로만 디코딩하고, LruCache<Int,Bitmap>로 최근 페이지만 메모리에 남긴다. 캐시 크기 자체도 런타임의 최대 힙(Runtime.getRuntime().maxMemory())의 1/4로 자동 계산해, 저사양·고사양 기기 모두에서 합리적으로 동작하도록 설계했다.

7시스템 요구사항

빌드는 Android Studio 하나로 끝 — 실기기 요구사항은 낮다.

CI(ci.yml)는 매 push/PR마다 3개 트랙을 동시에 검증한다 — ① 우분투 러너에서 :shared:jvmTest + :app:assembleDebug(안드로이드 디버그 APK), ② macOS 러너에서 iOS 시뮬레이터 대상 shared 모듈 컴파일 + 테스트, ③ macOS 러너에서 실기기용 미서명 iOS IPA 빌드까지. JDK 17로 고정해 api.foojay.io 같은 외부 툴체인 다운로드 없이 완전히 오프라인·결정적으로 빌드되도록 명시적으로 맞춘 점도 실무적으로 배울 만하다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계. 본인 소유이거나 자유 배포(퍼블릭 도메인) 만화로 실습할 것.

9관련 기술 심화 학습 로드맵

이 저장소를 출발점으로, 6주 코스.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: batunii/chika
• THIRD_PARTY_NOTICES(라이선스·Manga109 고지): THIRD_PARTY_NOTICES.md
• 모델 재학습 파이프라인: training/README.md
• CI 워크플로: .github/workflows/ci.yml
• 패널 탐지 모델(HuggingFace): leoxs22/manga-panel-detector-yolo26n
• Manga109 데이터셋: manga109.org
• TensorFlow Lite 공식 문서: ai.google.dev/edge/litert
• Kotlin Multiplatform 공식 문서: kotlinlang.org/docs/multiplatform
• Jetpack Compose 공식 문서: developer.android.com/jetpack/compose
• 7-Zip-JBinding-4Android(RAR5 지원): omicronapps/7-Zip-JBinding-4Android
• Apache Commons Compress: commons.apache.org/proper/commons-compress