why-the-car-doesnt-crab

운전 초보에게
“핸들을 돌리면 네 바퀴가 다 같은 방향으로 도는 거 아니야?”
라는 질문을 받고, 말로는 도저히 설명이 안 돼서 만든 브라우저 기반 3D 시뮬레이터입니다.

특히 후진 주차에서:

• 왜 앞바퀴와 뒷바퀴 궤적이 다른지
• 왜 차가 게처럼 옆으로 안 가는지
• 왜 “머리로는 알겠는데 몸이 안 따라오는지”

를 눈으로 보여주는 데 초점을 맞췄습니다.

한 줄로 말하면:
“주차장에서 설명하다 답답해서 만든 Ackermann 조향 시각화 도구”

그리고 가능하다면:

배우자와 주차장에서 싸우지 말고, 이 시뮬레이터로 먼저 연수시키세요.

GitHub description

Visual 3D simulator for explaining why cars don’t move like crabs — especially when reverse parking confuses beginners.

데모

• GitHub Pages: https://hojin-choi.github.io/why-the-car-doesnt-crab/

무엇을 보여주나

• 단순한 3D 자동차 + 주차장 장면
• 두 가지 조향 개념 비교
  • 실제 자동차 모드: 안쪽/바깥쪽 앞바퀴 각도가 다르게 움직이는 전륜 조향
  • 오해 모드: 네 바퀴가 같은 방향을 보는 가상 모드
• 앞/뒤 바퀴 궤적 시각화
• 여러 카메라 모드
  • 자유 카메라
  • 차 중심 고정 카메라
  • 운전석 뷰
• 운전석 뷰 보조 패널
  • 좌측 미러
  • 후방 카메라
  • 우측 미러
• 후진 주차 설명용 가이드라인 오버레이

이 프로젝트가 다루는 대표 오해

• “핸들 돌리면 바퀴 네 개가 다 같은 방향으로 도는 거 아니야?”
• “왜 후진할 때는 차가 생각한 쪽으로 바로 안 움직이지?”
• “왜 앞은 저렇게 가는데 뒤는 저 궤적을 따라가?”

이 프로젝트는 이런 질문에 대해 수식보다 장면으로 설명하는 것을 목표로 합니다.

기술 스택

• React
• Vite
• three.js
• @react-three/fiber
• @react-three/drei

시작하기

의존성 설치:

npm install

개발 서버 실행:

npm run dev

기본 주소:

• http://127.0.0.1:4173/

프로덕션 빌드 미리보기:

npm run preview

앱 빌드:

npm run build

standalone HTML 생성

단일 HTML 파일로 추출하는 스크립트도 포함되어 있습니다.

npm run build:standalone

다만 이 결과물은 git에 포함하지 않도록 설정해두었습니다.

이유:

• 생성 산출물이라 파일이 큼
• diff가 지저분하고 리뷰가 어려움
• 실제 프로젝트 이력은 소스코드와 빌드 스크립트에 남는 편이 낫기 때문

standalone 파일이 필요하면 로컬에서 직접 생성해서 사용하면 됩니다.

저장소 구조

src/
  App.jsx
  main.jsx
  styles.css
scripts/
  make-standalone-html.mjs

보안 관련 메모

이 프로젝트는 정적 프론트엔드 시뮬레이터입니다.

• 백엔드 없음
• 인증 없음
• 데이터베이스 없음
• 사용자 계정 시스템 없음
• 소스코드 내 API 키/비밀값 처리 없음

공개 저장소에는 소스코드와 빌드 스크립트를 커밋하고, standalone 산출물은 필요 시 로컬 생성 또는 별도 배포 산출물로 다루는 방식을 권장합니다.

Contributing

작은 버그 수정이나 설명 개선 PR은 언제든 환영합니다.
큰 구조 변경이나 UI 방향 변경은 먼저 issue로 의도를 공유해주면 좋아요.

영문 README

영문 버전은 아래 파일에 있습니다.

• README-en.md

라이선스

MIT