요런 — 내 주변 길에서 찾는 드로잉 러닝

지도에 보이는 동네의 실제 길만 따라 한 번에 달릴 수 있는 그림 코스(하트·별·고양이 등)를 찾아 주고, GPS로 코스를 안내하며 기록한 뒤, 달린 선을 작품방에 걸어 보관·공유하는 러닝 웹 앱(PWA)입니다.

지도에서 동네 맞추기 → 그림·거리 선택 → 코스 찾기 → 코스 골라 달리기(GPS 안내·기록) → 작품방에 걸기 → PNG/공유

러닝 아트 프로그램 설계 명세서 v1.0 기준으로 보면, 15절 ‘장기 경로 생성’을 시제품으로 구현해 앱의 중심 기능으로 두었고, P0(GPX → 작품 → 작품방 → 저장·공유)는 그대로 이어 붙였습니다.

실행

npm install
npm run dev            # http://localhost:3000  → /routes 에서 코스 찾기

• 위치(GPS)는 보안 연결(HTTPS) 또는 localhost에서만 동작합니다. 휴대폰에서 시험하려면 HTTPS로 배포하거나 npx next dev --experimental-https를 쓰세요.
• 홈 화면에 추가하면 앱처럼 열립니다 (/manifest.webmanifest, 시작 주소 /routes).
• Supabase 환경변수가 없어도 코스 찾기·달리기·임시 작품방·PNG는 동작합니다. 로그인 저장·공유는 아래 설정이 필요합니다.

Supabase 연결 (작품방 저장·로그인·공유)

1. supabase/migrations/0001_init.sql을 Supabase 프로젝트에서 실행합니다.
2. Auth → Redirect URLs에 http://localhost:3000/auth/callback(및 배포 주소)을 추가하고 이메일 로그인 링크 수신을 시험합니다.
3. .env.example을 .env.local로 복사해 채웁니다. SUPABASE_SERVICE_ROLE_KEY는 서버의 공유 조회에서만 씁니다.

드로잉 코스 찾기 동작 (src/lib/route/)

1. 길 데이터: 지금 지도 화면 영역(최대 4.5km × 4.5km)의 보행 가능한 길을 OpenStreetMap Overpass API에서 받습니다 (osm.ts). 고속도로·자동차 전용·보행 금지·사유지는 제외, 계단은 옵션으로 제외, 큰길은 비용을 높여 덜 선호합니다.
2. 길 단순화 (화면에서 선택, 기본 ‘큰길 위주’): 그림이 삐죽해지는 주원인인 잔길을 뺀 도로망에서 찾습니다.
   • 큰길 위주: 간선·생활도로(이름 있거나 150m 이상)·이름 있는 산책로만. 보도·횡단보도·진입로·서비스도로·연결램프 제외
   • 보통: 도로를 한 번 더 그린 보도·횡단보도와 진입로·짧은 무명 보행로만 제외 / 상세: 모든 보행로
   • 모든 수준에서 막다른 길은 잘라냅니다 (닫힌 코스에 쓰이지 않고 가시를 만듦). ‘탐색에 쓴 길 보기’로 지도에 겹쳐 볼 수 있습니다.
3. 도로 그래프: OSM 노드를 공유하는 길만 연결합니다. 교량·터널처럼 겹쳐 보여도 노드를 공유하지 않으면 연결로 보지 않습니다. 가장 큰 연결 요소만 씁니다 (graph.ts).
4. 배치 탐색: 그림 모양을 크기(목표 거리에서 역산) × 각도(±30°와 동네 도로의 주 방향) × 위치 격자로 놓아 보고, 미리 계산한 ‘가장 가까운 길까지 거리’ 격자로 빠르게 점수를 매깁니다 (fit.ts).
5. 경로 연결: 상위 배치의 기준점(꼭짓점 포함 ~40개)을 가까운 교차점에 붙이고, 기준점 사이를 모양 선분에서 벗어날수록, 급하게 꺾을수록 비용이 커지는 A*로 잇습니다. 한 구간이라도 못 이으면 그 배치는 버립니다 — 가짜 연결선·직선 메우기 없음. 결과는 출발점으로 돌아오는 한붓 경로입니다.
6. 가시·막대 정리: 같은 길 되돌이, 나란한 두 길로 나갔다 돌아오는 얇은 막대(평균 폭 25m 미만), 출발·도착 이음매에 걸친 막대를 짧은 길로 바꿉니다. 넓은 돌출(귀 등)은 유지합니다.
7. 평가·순위: 양방향 평균 이탈, 특징점(귀·별 끝) 보존, 그림과 무관한 급회전(지그재그), 가시 수, 반복·거리 이탈로 순위를 매기고 표시 유사도에도 반영합니다. 유사도 50 미만은 보여주지 않습니다.
8. 탐색은 Web Worker에서 돌아 지도 조작이 멈추지 않습니다. 같은 영역을 다시 찾으면 받은 데이터를 재사용합니다.

바탕 지도는 OpenFreeMap 벡터 지도(무료, API 키·가입 불필요, OpenStreetMap 데이터)를 MapLibre로 그립니다. 코스 찾기 화면은 글자·아이콘·건물을 뺀 단순 지도, 달리기 화면은 한국어 지명을 우선 표시하는 기본 지도(3D 건물 제외)입니다. 벡터 지도는 WebGL이 필요하며, 못 그리는 기기에서는 안내만 띄우고 코스 찾기·달리기는 그대로 동작합니다.

코스 품질 측정 (npm run eval:quality)

실제 OSM 데이터 3개 지역(부산 광안리·서면, 서울 강남, 각 약 2.53km 영역) × 9개 그림, 38km 조건. 알고리즘 자체 점수와 별개로 잰 값입니다.

지표	처음 버전	현재 (큰길 위주)
막대·가시 (코스당)	2.04개	0.04개
그림과 무관한 급회전 (1km당)	8.7회	5.3회
특징점(귀·꼭짓점) 보존	94%	100%
모양 이탈 95% 값 (모양 크기 대비)	3.6%	4.9%

잔길을 빼서 선이 깔끔해지는 대신 모양에서 조금 더 벗어납니다(마지막 행). 바둑판 도로가 많은 동네(강남)에서 가장 잘 나오고, 길이 불규칙한 동네(광안리·서면)에서는 고양이 귀처럼 작은 특징이 약해집니다. 측정하려면 Overpass에서 받은 JSON(busan.json, seomyeon.json, gangnam.json)을 한 폴더에 두고 EVAL_DIR=<폴더> npm run eval:quality를 실행합니다.

그림: 하트 · 별 · 동그라미 · 네모 · 세모 · 다이아몬드 · 고양이 · 물고기 · 번개 (shapes.ts에 단위 좌표 외곽선을 추가하면 늘어납니다).

달리기 (/run, src/lib/run/tracker.ts)

• GPS 위치로 코스 진행률·남은 거리·다음 방향(“60m 앞 우회전”), 40m 이상 3회 연속 이탈 시 경고·진동.
• 정확도 35m 초과·초속 8.5m 초과 순간 이동은 기록에서 제외. 일시정지 후 재개는 새 구간(끊긴 곳을 잇지 않음).
• 화면 꺼짐 방지(Wake Lock), 5초마다 이 기기에 진행 기록 보관 → 새로고침·종료 후 이어 달리기.
• 완료 후: 달린 GPS 선 그대로 작품방에 걸기(계획 코스로 빈 곳을 메우지 않음) · GPX 저장. 코스 없이 자유롭게 달리기도 가능.

시험

이미지 인식 비교 실험

npm run lab -- all --run experiment-01 --limit 24 --channel msedge로 동일 후보의 이진·회색 입력 비교와 블라인드 사람 평가 화면을 만듭니다. 결과는 eval/recognition/experiment-01/에 저장합니다. 선택형 SigLIP 2·CLIP 및 서버 VLM 실행, 평가 JSON 집계는 실험실 사용법을 참고하세요. 기본 실행은 외부 AI를 호출하지 않습니다.

푸시·PR마다 GitHub Actions가 타입 검사 → lint → 단위·품질 회귀 테스트 → 빌드 → 브라우저 E2E를 돌립니다. 층별 설명·원칙·명령은 docs/testing.md에 있습니다.

명령	내용
npm run typecheck · npm run lint	TypeScript 7 타입 검사 · ESLint (next core-web-vitals + typescript)
npm test	단위 테스트 (알고리즘·파서·계약·외부 서버 주고받기(MSW)·화면 조각·탐색 결정성) + 코스 품질 기준선
npm run test:quality	고정한 실제 지도(강남 2곳)에서 코스 품질이 기준선보다 나빠지지 않았는지 (:update로 기준선 갱신)
npm run test:e2e	Playwright: 작품방·코스 찾기·달리기·화면 이동 회귀·360px (외부 서버는 가짜 응답, 서버는 자동 기동)
npm run test:e2e:live	실제 바탕 지도 서버가 키 없이 뜨는지 (CI 제외)
npm run test:db	DB 마이그레이션(RLS·RPC·권한) — PGlite
npm run eval:make-set · npm run eval:calibrate	사람 판정으로 점수 등급 기준선 보정

실제 부산 수영·광안리 일대(약 2.5km 영역, OSM 4,151 노드) 측정: 9개 그림 전체 탐색 1.4~4초(헤드리스 Edge), 모든 그림에서 연결된 닫힌 코스(유사도 8188, 3.16.2km, 같은 길 반복 0~0.6%).

구조

src/lib/route/     osm(Overpass 질의·필터) · graph(투영·CSR 그래프·공간 색인·A*) · shapes · fit(탐색) · finder.worker
src/lib/run/       tracker(진행 추적·방향 안내·기록 필터·GPX) · storage(기기 보관)
src/components/    map/useLeafletMap · route/RouteFinderApp · run/RunApp · room/* · SceneSvg · ImportPanel
src/app/           / · /routes · /run · /room · /share/[token] · /api/* · manifest
src/lib/(gpx|art|contracts|room|render|draft|server)   GPX → 작품 → 작품방 (명세 P0)
supabase/          마이그레이션 + DB 검증 스크립트
e2e/               Playwright 테스트(specs·fixtures) + 수동 디자인 캡처 도구(tools)
tests/             단위·화면 조각·품질 기준선 테스트, 공용 가짜 응답(mocks), 고정 지도 데이터(fixtures)

아직 하지 않은 것 / 알려진 한계

• 실제 휴대폰에서 달려 보는 시험은 아직 안 했습니다. GPS 흔들림·건물 사이 오차·배터리, 방향 안내 타이밍은 실기기로 조정해야 합니다.
• 웹 앱의 백그라운드 위치 제한: 화면이 꺼지거나 다른 앱으로 가면 기록이 멈출 수 있습니다 (안내 문구 표시). 화면을 끄고 달리는 기록이 필수라면 네이티브 앱(React Native/Capacitor 등)으로 감싸야 합니다.
• 지도 데이터: OSM은 실제 통행 가능 여부·공사·임시 통제·보도 유무·야간 조명을 보장하지 않습니다 (화면에 미확인으로 표시). 지역에 따라 데이터 누락이 있습니다.
• 공개 서버 사용: 길 데이터(Overpass)와 바탕 지도(OpenFreeMap)는 무료 공개 서버입니다. 키는 필요 없지만 기부로 운영되므로, 실제 서비스 규모에서는 사용량을 확인하고 자체 서버(OpenFreeMap은 자체 설치 가능)도 검토해야 합니다. 지도 영역 좌표가 이 서버들로 전송됩니다 (화면에 안내).
• 그림 품질 한계: 길 간격보다 작은 특징(불규칙한 동네의 고양이 귀 등)은 약해질 수 있고, 바둑판 도로에서 비스듬한 선은 계단 모양이 됩니다. 유사도는 사람이 느끼는 ‘닮음’과 다를 수 있습니다. 거리를 늘리면 그림이 커져 덜 뭉개집니다.
• MapLibre Worker 파일: 타일 처리 Worker를 public/vendor/로 복사해 앱이 직접 제공합니다. npm install·npm run dev·npm run build 때 자동으로 복사됩니다 (scripts/copy-maplibre-worker.mjs).
• 공공 API: 아직 쓰지 않습니다. 명세 15.2~15.3절 후보(전국보안등정보 → 야간 밝은 길 가중치, 기상청 단기예보 → 달리기 시각 추천)는 데이터 검증 표를 채운 뒤 경로 비용에 넣는 것이 다음 단계입니다.
• 작품방 저장·공유는 실제 Supabase 프로젝트에서 시험하지 않았습니다 (DB 로직은 PGlite로 검증).

한국 길 데이터 설치·갱신 및 배포 방법: docs/local-roads.md.