이미지 수집
Pre-Signed 모드와 고객 URL 모드, 모듈 스코프 슬롯 키, 캡처 구성(템플릿)을 설명합니다.
분석에 쓰는 이미지 출처는 모드에 따라 다릅니다. 어느 모드든 이미지 바이트는 ATRACE Report API를 거치지 않습니다.
ATRACE 스토리지는 리포트를 안정적으로 표시하기 위한 이미지 보관 용도로만 운영하며, 고객사 스토리지와는 무관합니다.
두 가지 모드
모드 A — 고객 URL (immutable)
자사 스토리지에 이미지를 두고 변하지 않는 URL을 줄 수 있을 때 사용합니다.
POST /reports의images[].source.url에 URL을 넣습니다.- AI Engine API가 그 URL을 직접 읽어 분석합니다.
- 플랫폼이 그 이미지를 비동기로 ATRACE 스토리지에 복사해 리포트 표시에 사용합니다.
- 전제: URL은 변하지 않아야(immutable) 합니다. 분석한 이미지와 표시용 사본이 같아야 하기 때문입니다.
모드 B — Pre-Signed (ATRACE 스토리지)
이미지를 호스팅할 곳이 없을 때 사용합니다.
POST /reports를images없이 호출하면upload_targets[](업로드용 PUT URL)를 받습니다. 타이어 4개 위치 ×{tread, sidewall}= 8개 슬롯 전체가 항상 발급됩니다.- 실제로 촬영한 슬롯의
upload_url에만 이미지를 PUT 합니다. 업로드는 스토리지로 바로 가고, ATRACE Report API를 거치지 않습니다. POST /reports/{id}/images로 실제 업로드한 슬롯만 등록하면 분석이 시작됩니다. 이미 성공한 슬롯을 다시 등록하면409(SlotConflict)가 반환되며, 덮어쓰려면?replace=true를 붙여 교체(재분석)합니다.
사이드월 위치는 고정이 아닙니다. 현장 요원이 공간 제약으로 특정 방향만 촬영할 수 있어, 사이드월 2장이 (앞좌 + 뒤우) 등 어떤 조합으로든 올 수 있습니다. 그래서 8개 슬롯을 모두 발급하고 파트너 앱은 실제 촬영한 슬롯에만 업로드·등록합니다. 사이드월의 좌·우를 알 수 없으면 좌·우 중 한쪽을 임의로 선택해 업로드해도 됩니다.
Pre-Signed 업로드 규약
upload_url은 Supabase Storage의 서명 업로드 URL입니다.
- 메서드: HTTP
PUT— 원본 이미지 바이트를 본문에 그대로 실어 보냅니다. Content-Type:image/jpeg또는image/png.- 성공 응답:
200. - 만료: 발급 후 12시간. 만료 후 재발급 엔드포인트는 현재 없습니다(추후 고객 요청 시 고려).
ATRACE Report API는 이미지 바이트를 직접 받지 않습니다
/images 엔드포인트는 참조(슬롯·URL)만 받습니다. 용량이 큰 이미지를 API로 직접 보내면 바디 한도와 지연 문제가 생기기 때문입니다.
바이트는 항상 스토리지로 직접 PUT 하거나, AI Engine API로 직접 보냅니다.
이미지 요구사항
- 포맷: PNG 또는 JPEG.
- 해상도: 가급적 Full HD(1920×1080)급 이상을 권장합니다.
- JPEG 압축 품질: 정식 분석에 쓰는 이미지는 0.95 수준을 권장합니다(규격 OCR·트레드 측정 정확도). 촬영 직후 판독 사전점검(precheck)에만 쓰는 이미지는 0.85까지 낮춰 지연·용량을 줄여도 됩니다. 자세한 기준은 이미지 품질.
- 회전: 클라이언트가 EXIF 회전을 보정할 필요가 없습니다. AI가 시각적으로 회전을 판단하고, 리포트 시각화 시 이미지를 바로 세웁니다. HEIC/EXIF 정규화도 불필요합니다.
모듈 스코프 슬롯 키
이미지는 { module_type, slot }로 식별합니다. slot의 형태는 모듈마다 다릅니다.
{ "module_type": "tire", "slot": { "position": "front_left", "image_type": "tread" } }| module_type | slot 형태 |
|---|---|
tire | { position: front_left | front_right | rear_left | rear_right, image_type: tread | sidewall } |
dashboard | {} 또는 { kind } (단일) |
plate | {} (단일) |
exterior | { panel: ... } |
현재는 tire 모듈만 지원합니다. 계기판(dashboard)·번호판(plate)·외장(exterior)은 추후 확장 예정이며, 위 표는 참고용입니다. position은 타이어 전용이며 slot 안에 들어갑니다.
새 모듈이 추가돼도 기존 계약은 깨지지 않습니다.
캡처 구성은 템플릿이 정한다
리포트가 어떤 이미지를 몇 장 요구하는지는 템플릿이 정의합니다(고정 8장이 아닙니다).
| 템플릿 | 구성 |
|---|---|
tire_4t_2s | 트레드 4장 + 사이드월 2장 = 6장 |
tire_4t_4s | 트레드 4장 + 사이드월 4장 = 8장 |
template 필드를 생략하면 조직 기본 템플릿이 적용됩니다. 어떤 슬롯이 필수인지는 GET /reports/{id} 응답의
slots[].required로 확인합니다.