📦 레포: kh20134/jev-vehicle-classifier (MIT, v0.1.1, 커밋 7a53fd2)
🧭 연재: ① 개요 및 초기 구조 (이번 글) → ② 실제 검출 → ③ 데이터·라벨 → ④ confidence 보정 → ⑤ 현장 ITS 연계
1. 연재 배경
- 교통량 조사는 도로 계획·설계·운영의 기초 자료임. 차종별·방향별·시간대별로 통과 대수를 셈
- 고속국도·일반국도 상시조사는 AVC 장비로 365일 24시간 연속 수집함
- 고속국도 수시조사는 매년 10월 셋째 주 목요일에 AVC·VDS·TCS와 CCTV 인력 조사를 병행함
현장에서 체감하는 문제는 매설식 AVC의 한계였음.
- 노면 매설 센서(피에조 등)로 축수·축간거리·차량길이를 재고 제원과 비교해 분류하는 방식임
- 센서 관리 상태에 분류 정확도가 크게 좌우됨
- 편향 주행, 센서 손상 같은 현장 변수에 능동 대응이 어려움
- 매설식이라 재포장·보수 때 센서 재시공이 따르고, 수시조사에서는 결국 CCTV 인력 조사를 병행함
그래서 CCTV 영상에서 특징을 뽑고, 마지막 차종 판단은 결정 모델에 맡기는 구조를 연재로 만들어 보기로 했음.
2. TypeSafe Jev란
- TypeSafe의 System One 모델 중 첫 번째이자 대표 모델임
- 상태(state)를 읽고 정해진 답과 확률을 돌려주는 결정 모델임. 글을 생성하는 LLM과 다름
- 질문 유형은 Choice(선택지 중 하나), Score(척도), Noul(참/거짓) 세 가지임
- Choice 응답은
choice, 선택지별probabilities, 분포 모양으로 계산한confidence로 구성됨 - 입력은 현재 텍스트만 받음. 문자열, JSON 객체, 텍스트 배열까지임. 이미지·음성·영상은 미지원임
3. 왜 비전 → 특징 → state → Choice인가
- Jev에 CCTV 화면을 바로 넣을 수 없음. 화소를 글로 바꾸는 단계가 반드시 필요함
- 차종 분류표가 실제로 묻는 건 축수, 단위(트레일러 연결 여부), 세미/풀 형식, 적재 톤임
- 비전은 그 값을 뽑는 데만 집중하고, 12종 판단은 Jev Choice가 맡도록 역할을 나눴음
- 검출기는 YOLO가 될 수도, 현장 검지기 값이 될 수도 있음. state JSON만 고정하면 앞단을 갈아 끼워도 Choice 층은 그대로임
영상 또는 샘플 JSON → 특징(VehicleFeatures) → state JSON → Jev Choice → 12종 + 확률
└ 표 밖이거나 confidence가 낮으면 TRA_미분류4. 도로교통량조사 12종 차종분류
기준은 한국건설기술연구원 교통량정보제공시스템의 12종 차종분류표임. 축수와 단위로 나눔.
- 1단위: 차체 하나
- 2단위: 견인차+피견인차 조합을 한 대로 셈. 축수도 조합 전체로 셈
- 버스는 16인승 이상이면 한 종임. 이륜차 칸은 없음
| 코드 | 종별 | 축·단위 | 정의(요약) | AVC 열 |
|---|---|---|---|---|
| class_01 | 1종 승용차·미니트럭 | 2축 1단위 | 16인승 미만 여객, 미니트럭 | TRA_01종 |
| class_02 | 2종 버스 | 2축 1단위 | 16인승 이상 여객 버스 | TRA_02종 |
| class_03 | 3종 소형화물차 A | 2축 1단위 | 최대 적재 1~2.5톤 미만 | TRA_03종 |
| class_04 | 4종 소형화물차 B | 2축 1단위 | 최대 적재 2.5톤 이상 | TRA_04종 |
| class_05 | 5종 중형화물차 A | 3축 1단위 | 화물 트럭 | TRA_05종 |
| class_06 | 6종 중형화물차 B | 4축 1단위 | 화물 트럭 | TRA_06종 |
| class_07 | 7종 중형화물차 C | 5축 1단위 | 화물 트럭 | TRA_07종 |
| class_08 | 8종 대형화물차 A | 4축 2단위 | 세미 트레일러 | TRA_08종 |
| class_09 | 9종 대형화물차 B | 4축 2단위 | 풀 트레일러 | TRA_09종 |
| class_10 | 10종 대형화물차 C | 5축 2단위 | 세미 트레일러 | TRA_10종 |
| class_11 | 11종 대형화물차 D | 5축 2단위 | 풀 트레일러 | TRA_11종 |
| class_12 | 12종 대형화물차 E | 6축 이상 2단위 | 세미 트레일러 | TRA_12종 |
출처: 한국건설기술연구원 교통량정보제공시스템 「도로교통량조사 12종 차종분류표」 (road.re.kr, 2026-10-17 확인). AVC 열 이름은 한국도로공사 고속도로 AVC 원시자료(공공데이터포털) 기준
- 코드
class_01~class_12는 AVC 원시자료TRA_01종~TRA_12종과 순서를 맞췄음 - 원시자료에 있는
TRA_미분류는 Choice 선택지로 넣지 않았음 (9장 참고) - 이륜차, 6축 이상 풀트레일러처럼 표에 없는 차량은
TRA_미분류로 집계함
5. 전체 구조
연재 1회 파이프라인 구조도 · 출처: kh20134/jev-vehicle-classifier docs/diagrams/architecture.png (커밋 7a53fd2)
- ① 입력: 도로 CCTV를 가정함. 이번 회차는 샘플 특징 JSON을 읽음
- ② 비전 특징 추출:
MockVisionExtractor가 자리만 잡음. 이미지·가중치 사용 안 함 - ③ state 구성: 축수, 단위(트레일러), 적재 톤을
VehicleFeatures.to_state()로 JSON화함 - ④ TypeSafe Jev: Choice 하나, 선택지 12개 (
jev-latest) - 출력: 차종 코드·한글명·확률분포·AVC 집계 열, 저신뢰는
needs_review
6. 프로젝트 구조
src/jev_vehicle/classes.py 12종, TRA_01종~TRA_12종, Choice criteria
src/jev_vehicle/features.py 축수, 단위, trailer_type, load_tonnage_t, to_state()
src/jev_vehicle/vision_mock.py 연재 1회 mock 추출기 (extract()가 계약)
src/jev_vehicle/classifier.py Jev 호출, MockJevClient, TRA_미분류 라우팅
src/jev_vehicle/cli.py python -m jev_vehicle
examples/sample_features/ 샘플 특징 JSON 14종
tests/ 키 없이 도는 단위 테스트- 특징 JSON에 정답 코드는 넣지 않음
- 번호판, 얼굴, 영상 바이트도 필드로 두지 않음. 개인정보는 처음부터 경로에서 뺐음
- 연재 2회 검출기는
extract()가 같은VehicleFeatures만 돌려주면 됨
7. 설치 및 테스트
git clone https://github.com/kh20134/jev-vehicle-classifier
cd jev-vehicle-classifier
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest- Python 3.10 이상 필요함
- mock 모드와 테스트는
typesafe-sdk, API 키 없이 동작함
설치 후 단위 테스트 35개 통과 · 출처: 직접 실행 (2026-10-17 KST, Python 3.13, 커밋 7a53fd2)
8. 실행 화면 (mock)
아래 화면은 전부 --mock 실행임. 실제 Jev 응답이 아님. 확률 값은 데모 규칙이 만든 고정 분포임.
python -m jev_vehicle classify --sample sedan --mock
python -m jev_vehicle classify --sample bus --mock
python -m jev_vehicle classify --sample truck3axle --mock
python -m jev_vehicle classify --sample semi5 --mock
python -m jev_vehicle classify --sample motorcycle --mock① 승용차 (sedan)
2축 1단위, 5인승 → class_01, 집계 TRA_01 · 출처: 직접 실행 (2026-10-17 KST, mock)
② 버스 (bus)
45인승 버스 → class_02, 집계 TRA_02. 좌석형·입석형 구분 안 함 · 출처: 직접 실행 (2026-10-17 KST, mock)
③ 3축 단일 트럭 (truck3axle)
3축 1단위 → class_05 중형화물 A, 집계 TRA_05 · 출처: 직접 실행 (2026-10-17 KST, mock)
④ 5축 세미트레일러 (semi5)
5축 2단위, 세미 → class_10 대형화물 C, 집계 TRA_10. 견인차·피견인차를 한 대로 셈 · 출처: 직접 실행 (2026-10-17 KST, mock)
⑤ 이륜차 (motorcycle) → TRA_미분류
표 밖 차량(out_of_scope) + 저신뢰 → 집계 TRA_미분류, needs_review · 출처: 직접 실행 (2026-10-17 KST, mock)
- Choice는 12개 중 하나(여기선 class_01)를 고르지만, 집계 칸은
TRA_미분류로 감 - Choice가 고른 코드는 리포트에 남기고, 자동 집계에 쓰는 값은
집계칸임
9. 미분류와 needs_review 임계값
TRA_미분류는 13번째 차종이 아님. 애플리케이션이 정하는 집계 처리임- Choice 선택지에 미분류를 넣으면 확률이 차종 아닌 쪽으로 새고, AVC 12개 열과 어긋남
- 그래서 Jev는 항상 12개 중 하나를 고르게 두고, 뒤에서 라우팅함
이륜차 등 표 밖 → 집계 TRA_미분류, needs_review
confidence < 임계값 → 집계 TRA_미분류, needs_review
그 외 → 집계 TRA_01 … TRA_12- 기본 임계값은
0.45임. 12지선다에서 최상위 확률 약 0.50에 해당함 - confidence는 "맞을 확률"이 아니라 확률이 한곳에 얼마나 몰렸는지를 0~1로 나타낸 값임
0.45는 자리표시자임. 현장 라벨로 보정하기 전엔 운영 기준으로 쓰지 않음--threshold옵션으로 바꿔 볼 수 있음
10. 이번 회차의 한계
- 비전 단계는 mock임. 실제 CCTV 이미지를 열지 않음
- 모든 실행 화면은
MockJevClient결과임. 공식 판정도 아니고 Jev 응답도 아님 - 실제 Jev(
--live) 호출은 아직 검증하지 않았음. 코드 경로와 SDK 사용법(response.answers)만 문서 기준으로 맞춰 둠 - 정확도·처리 속도 같은 성능 수치는 아직 없음. 라벨 데이터가 생기는 3회부터 측정함
- 임계값 0.45는 보정 전 값임
11. 다음 연재 예고
| 회차 | 내용 |
|---|---|
| ① 이번 글 | 공식 12종, mock 특징, state, Jev Choice, TRA_미분류 |
| ② 실제 검출 | YOLO 등으로 차량 검출. 가림·야간·원거리 누락값은 null로 표현. Jev 입력은 계속 state |
| ③ 데이터·라벨 | 평가 세트, 혼동행렬. 1톤·2.5톤 경계, 세미/풀, 축 하나 잘못 센 조합 사례 정리 |
| ④ confidence 보정 | 현장 라벨로 임계값 선정. 자동 집계 비율과 사람 검토 비율 동시 확인 |
| ⑤ 현장 ITS 연계 | AVC 원시자료 TRA_01종~TRA_12종·TRA_미분류 집계, 검토 큐, 지점·차로 메타데이터 분리 |
12. 한눈에 정리
| 구분 | 내용 |
|---|---|
| 목표 | CCTV 차량을 도로교통량조사 12종으로 분류 |
| 결정 모델 | TypeSafe Jev (System One) Choice, jev-latest |
| Jev 입력 | state JSON (축수·단위·트레일러 형식·적재 톤). 이미지 아님 |
| 집계 열 | TRA_01종~TRA_12종 + TRA_미분류 |
| 검토 기준 | confidence < 0.45 또는 표 밖 → needs_review |
| 1회 범위 | mock 특징·mock 응답, CLI, 테스트 35개 |
| 레포 | kh20134/jev-vehicle-classifier |
GitHub 저장소 메인 화면 · 출처: github.com/kh20134/jev-vehicle-classifier (2026-10-17 KST 캡처)
13. 출처
- 한국건설기술연구원 교통량정보제공시스템, 도로교통량조사 12종 차종분류표
- 한국건설기술연구원 교통량정보제공시스템, 도로교통량조사 개요·목적 및 적용범위
- 공공데이터포털, 한국도로공사_고속도로 AVC원시자료
- 김형수 외, 차량길이와 축거의 추세선을 이용한 차종분류 알고리즘 개발, 대한교통학회지 (2009)
- 3-Piezo 센서 기반 교통량 조사시스템의 차종분류방식에 대한 연구 (earticle)
- TypeSafe Docs: Quickstart · System One · Choice