tta-uds-streamer/README.md

# tta-uds-streamer

## 📘 TTA UDS Streamer
C 모듈이 전송하는 **UDS 기반 프레임/디텍션 스트림**을 처리하는 Python 모듈

---

## 📌 개요
이 프로젝트는 C 측에서 **Unix Domain Socket(UDS)** 을 통해 전송되는

- JPEG 프레임(FRA)
- 디텍션(UDSD)

데이터를 Python에서 수신하여

- 프레임 버퍼링
- 디텍션 타임스탬프 매칭
- WebSocket 실시간 스트리밍

까지 처리하는 파이프라인을 제공합니다.

본 저장소는 **Python 측 모듈만 포함**하며  
C 측 **NPU → Postprocess → UDS 모듈(cam_ws_app 등)** 과 연동하여 동작합니다.

---

## 📁 디렉토리 구조

```text
tta-uds-streamer/
│
├── uds_postprocessing.py      # 전체 파이프라인 처리 모듈
│
├── feat_control/              # 기능 제어 모듈
│   └── ctrl_cli.py            # 기능 ON/OFF 제어 CLI (UDS 제어)
│
├── requirements.txt           # 패키지 목록
│
└── README.md
```

---

## 🔧 패키지 설치

```bash
pip install -r requirements.txt
```

---

## 🚀 전체 파이프라인 실행

```bash
python uds_postprocessing.py
```

C 프로그램이 `/tmp/cam.sock` UDS 소켓으로 아래 포맷을 전송하면  
Python은 프레임 및 디텍션을 자동으로 처리합니다.

---

## 📡 데이터 포맷 요약

### 📌 FRA (Frame)

| 필드 | 설명 |
|------|------|
| magic | "FRA\0" |
| width / height | JPEG 이미지 크기 |
| stride | JPEG 바이트 길이 |
| pixfmt | WS_PIXFMT_JPEG |
| ts_us | 프레임 타임스탬프(μs) |
| payload | JPEG binary |

---

### 📌 UDSD (Detection)

| 필드 | 설명 |
|------|------|
| magic | "UDSD" |
| count | 디텍션 수 |
| ENTRY | prob, x, y, w, h, cls, ... |
| ts_us | 디텍션 타임스탬프(μs) |

---

## 🧩 기능 요약

- 최근 프레임 N장 버퍼링  
- 디텍션 타임스탬프와 가장 가까운 프레임 자동 매칭  
- WebSocket 실시간 스트리밍 지원
- C 모듈 기능 플래그를 UDS로 실시간 제어 가능  

---

# 🎮 Feature Control 사용법

`ctrl_cli.py` 와 `ctrl_features.sh` 를 사용하여  
C 스트리머 기능(OBJDET, FIRE, FACE 등)을 ON/OFF 할 수 있습니다.

---

## 📁 관련 파일

```text
feat_control/
├── ctrl_cli.py        # 기능 제어 메시지를 UDS로 전송하는 Python CLI
└── feat_on.sh       # 여러 기능을 한 번에 ON/OFF 제어하는 스크립트
```

---

## 🔧 ctrl_features.sh 사용법

### 기본 구조

```bash
./ctrl_features.sh FEATURE [FEATURE ...]
```

### 예시

#### 객체 탐지 활성화
```bash
./feat_on.sh OBJDET
```

#### 객체 탐지 + 화재 탐지
```bash
./feat_on.sh OBJDET FIRE
```

---

## 🧩 ctrl_cli.py 동작 요약

`ctrl_cli.py`는 다음을 수행합니다:

1. UDS 제어 소켓(`/tmp/ctrl_feat.sock`) 연결  
2. 명령 문자열 전송  
3. OK / FAIL 응답 수신  

C 측에서는 이 명령을 기반으로  
`ctrl_flags.h` 에 정의된 기능 플래그를 실시간 업데이트합니다.

---