fieldcards: 로컬 Gemma를 이용해 사진을 인쇄 가능한 보물찾기(scavenger hunt)로 변환하기

이 글은 Hacktoberfest Open-Source AI Challenge: Week 1 (테마: Touch Grass)에 제출하는 내용입니다.

제가 만든 것

fieldcards는 노트북 속 사진들을 인쇄 가능한 보물찾기 활동으로 변환해 주는 커맨드라인 도구입니다.

공원, 정원 또는 산책로에서 찍은 사진 폴더를 이 도구에 지정합니다. Ollama를 통해 로컬에서 실행되는 Gemma 3가 각 사진을 살펴보고, 그 안에서 가장 찾기 쉬운 것을 파악하여 그것을 직접적으로 언급하지 않는 단서를 작성합니다. 각 단서는 인쇄 가능한 ASCII 카드 형태로 만들어집니다. 이 시트를 출력하고 휴대폰은 집에 두고 나가서 실제 사물을 찾아다니는 것입니다.

화면으로 보는 것이 가장 짧습니다: 시트 제작에 약 2분 정도 걸리고, 나머지 오후 시간은 야외에서 보내게 됩니다.

+-[ #05 other ]----------------+
|
|	어둡고 풍화된 것을 찾아보세요
...

이 카드는 이끼 낀 통나무가 숲속 폭포를 가로지르는 사진에 대한 실제 gemma3:4b 출력물입니다.

데모

단 하나의 커맨드로 실행됩니다:

ollama pull gemma3:4b
npm install -g github:KunalSiyag/fieldcards
fieldcards ./photos --title "Saturday in the park"

제 터미널에서 실제 실행 과정을 보여드립니다. --stdout은 카드를 바로 출력하고, 진행 상황은 stderr로 전송되므로 fieldcards ./photos --stdout | lp를 사용하면 프린터로 곧바로 전송됩니다:

실행할 때마다 세 개의 파일이 생성됩니다:

• index.html: 페이지당 6장의 카드와 정답지가 포함된 인쇄 준비가 된 시트.
• cards.txt: 일반 텍스트 형태의 카드들. --cols 32는 폭 58mm 영수증 프린터에 적합합니다.
• deck.json: Gemma가 말한 모든 내용. 실수가 있다면 수정하고, 모델을 다시 실행하지 않고도 --from 옵션으로 재인쇄할 수 있습니다.

--mode guide를 사용하면 동일한 사진을 수수께끼 대신 이름과 설명이 포함된 주머니 크기의 필드 가이드(field guide)로 바꿀 수 있습니다.

제가 찍은 실제 사진

위 실행에서는 이 글을 작성하는 동안 제가 가지고 있던 유일한 개인 사진, 즉 최근 방문했던 양조장의 바 카운터 사진을 사용했습니다. 야외 장면은 아니지만, 실제로 붐비는 곳의 전체 파이프라인을 보여줍니다.

Gemma는 7초 만에

각 사진은 Ollama를 통해 로컬에서 실행되는 Gemma 3으로 전송됩니다. Gemma는 사진이 무엇을 보여주는지 파악하고 그것의 이름을 직접 언급하지 않는 단서를 작성합니다. 그런 다음 **altsvg**가 이 모든 사진을 해당 단서가 담긴 인쇄용 ASCII 카드로 대체하는데, 이는 altsvg가 alt 텍스트를 플레이스홀더로 변환하는 방식과 같습니다. 이 시트를 인쇄하고 휴대폰은 집에 두고 실제 사물을 찾아 나섭니다.

+-[ #05 other ]----------------+
|
|	어둡고 풍화된 것을 찾아보세요
...

이 카드는 ...에서 실행된 실제 gemma3:4b에서 나온 것입니다:

GitHub에서 보기

제작 과정 (How I Built It)

1. 설명(Describe). 각 사진은 로컬 Ollama 서버의 POST /api/chat으로 전송되며, 여기에 format에 JSON 스키마가 함께 전달됩니다. Gemma는 답변을 할 때 subject, category, description, clue, look_for, where, 그리고 confidence를 포함해야 하므로, 자유로운 형식의 응답이 레이아웃을 망가뜨릴 수 없습니다.
2. 확인(Check). 답변은 검증되고 다듬어집니다. 만약 단서에 그 자체의 답이 포함되어 있다면, 그 답 부분은 공백 처리되며, 신뢰도가 낮은 답변은 카드에

• 예시 이름 유출. 프롬프트에 좋은 이름의 예시로 '민들레 씨앗 머리(Dandelion seed head)'를 추가했습니다. 다음 실행에서 Gemma는 폭포 사진을 '민들레 씨앗 머리'라고 분류했습니다. 작은 모델들은 예시를 복사하기 때문에 최종 프롬프트에서는 이 부분을 제거했습니다.
• 엄격한 문구 사용의 위험성. 확실할 때만 '높음(high)' 신뢰도를 사용하도록 지시했을 때, 모든 결과가 '낮음(low)'으로 나왔고 이름들이 모호해졌습니다('어두운 깃털을 가진 관찰자'). 원래의 단순한 프롬프트가 가장 효과적이었습니다. 저는 그것을 유지하고 단지 단서가 모두 '찾아라(Seek)'로 시작하지 않도록 규칙 하나만 추가했습니다.

잘된 점과 잘못된 점

테스트 사진에서 Gemma는 흔한 사물들, 즉 민들레 시계, 단풍잎, 폭포를 안정적으로 인식했습니다. 그 단서들은 답을 직접적으로 알려주지 않습니다. 하지만 세부적인 부분에서는 약했습니다. 까마귀는 '매끄럽고 어두운 새'로 돌아왔고, 부드러운 소나무 꽃가루 속임은 '목질의(woody)'로 묘사되었으며, 양조장은 '둥글고 반사되는 표면'이 되었습니다. 자체 평가된 신뢰도는 단지 대략적인 신호일 뿐이며, 이 세 가지 모두를 '높음(high)'으로 평가했습니다. 이것이 모든 답변이 인쇄하기 전에 확인하도록 deck.json에 들어가는 이유이고, 모든 시트에 '찾아보세요, 고르지 마세요(look, don't pick)'라고 쓰여 있는 이유입니다.

Open Source의 중요성

• 신호가 필요하지 않음. 모델이 노트북에서 실행되므로 오두막, 캠핑장 또는 어디서든 오프라인으로 카드 제작이 가능합니다.
• 사진은 사용자 소유로 유지됨. 사진에는 얼굴, 배경의 집, 메타데이터에 GPS 정보가 담겨 있습니다. 아무것도 업로드되지 않으며, 요청은 localhost로만 전송됩니다.
• 실행 비용이 들지 않음. API 키나 사진당 요금이 없으므로 선생님 한 분이 모든 학급을 위한 시트를 만들 수 있습니다.
• 교체 가능함. --model은 Ollama가 실행할 수 있는 모든 비전 모델을 사용하며, JSON 스키마는 출력 형태를 동일하게 유지합니다.

제 노트북(RTX 3050, 4 GB)에서 첫 번째 사진을 처리하는 데 약 2분이 걸리는데, 이는 모델 로딩 시간도 포함하기 때문입니다. 그 이후의 각 사진은 GPU 메모리 약 2.9 GB를 사용하며 7초에서 13초가 소요됩니다.

다음 단계

아직 인쇄된 사냥 활동을 외부에서 해보지 않았습니다. 그것이 다음 단계이며, 전체 디자인이 의존하는 테스트입니다. 제가 할 때 알아보고 싶은 것은 다음과 같습니다:

• 30분에서 60분 동안의 산책에 여섯 장의 카드가 적절한 크기인지;
• 단서가 재미있게 풀리는지 아니면 너무 모호한지, 특히 "최선의 추측(best guess)"이라고 표시된 카드가 그렇습니다.
• 아이들이 "급류가 흐르는 은빛 시냇물 옆에 기대어 쉬고 있는 어둡고 풍화된 거인"과 같은 수수께끼를 어떻게 처리하는지.

이 포스트에 시트 사용 사진을 추가하여 업데이트하겠습니다.

상(Prize) 부문

Gemma의 최적 활용. Gemma 3 4B가 프로젝트의 핵심입니다. 이 모델은 모든 사진을 로컬에서 읽고 JSON 스키마를 통해 카드 내용을 작성합니다.

크레딧

• Google의 [Gemma 3]이며, [Ollama]를 사용하여 로컬에서 실행합니다.
• [altsvg]는 저의 초기 오픈 소스 프로젝트입니다(2026년 3월 시작, npm에 게시됨). 이번 주에는 필드 카드용으로 ASCII 스타일이 추가되었습니다.
• [jpeg-js]와 [pngjs]는 선택적 --art 모드를 위해 사진을 디코딩하며, 이 모드는 사진 자체를 문자(character)로 출력합니다.
• 테스트 사진은 Wikimedia Commons에서 가져온 것입니다: Alexis Lours의 까마귀(CC BY 4.0)와 Dietmar Rabich의 폭포(CC BY-SA 4.0). 양조장 사진은 제가 찍었습니다.
• Claude Code의 도움을 받아 제작되었습니다.