> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dwe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# DWVO 녹화 파일 읽기

> Python과 OpenCV로 .dwvo 녹화 파일을 재생, 내보내기 및 파싱합니다.

<div style={{ marginTop: '-40px' }} />

<Tooltip tip="DeepWater Video Object">`.dwvo`</Tooltip>는 Discovery에서 녹화할 때 생성되는 당사의 다중 카메라 녹화 컨테이너입니다. 페이로드는 MJPEG이므로 파일의 모든 프레임은 이미 완전한 JPEG입니다 — 재생은 단일 `cv2.imdecode` 호출로 이루어지며, 내보내기는 재인코딩이나 품질 손실 없이 바이트 단위 복사로 처리됩니다.

<Card title="Discovery에서 DWVO 녹화하기" icon="video" href="/ko/discovery/misc/dwvo-support" horizontal>
  DWVO를 처음 사용하시나요? `.dwvo` 파일 스트리밍 및 녹화는 여기서 시작하세요.
</Card>

```
DWE.ai | header: nCameras, width, height, pixelFormat, fps | ext data
block:   uint32 timestamp | per camera: busID\0, uint32 length, JPEG bytes
block:   ...
```

## 사전 요구 사항

* Python (버전 3.x)
* `opencv-python`, `numpy`, `pillow`
* `.dwvo` 녹화 파일 — 아래 예제에서는 `test.dwvo`를 사용합니다

## 설정

OpenCV Guides 저장소를 클론하고 이 가이드에 해당하는 폴더를 연 뒤, 가상 환경을 만들고 의존성을 설치하세요:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  git clone https://github.com/DeepWaterExploration/opencv-guides.git
  cd opencv-guides/4-dwvo-read/python

  python3 -m venv venv
  source venv/bin/activate
  pip install -r requirements.txt
  ```

  ```bash Windows theme={null}
  git clone https://github.com/DeepWaterExploration/opencv-guides.git
  cd opencv-guides\4-dwvo-read\python

  python3 -m venv venv
  venv\Scripts\activate
  pip install -r requirements.txt
  ```
</CodeGroup>

## 재생

`main.py`는 모든 카메라를 디코딩하여 하나의 OpenCV 창에 나란히 표시합니다.

```bash theme={null}
python main.py test.dwvo
python main.py test.dwvo --fps 60 --loop
```

| 인수 / 키      |                         |
| ----------- | ----------------------- |
| `--fps N`   | 재생 속도. 기본값은 헤더의 fps입니다. |
| `--loop`    | 파일 끝에서 다시 시작합니다.        |
| `space`     | 일시 정지 / 재개.             |
| `q` / `esc` | 종료.                     |

<Note>
  재생은 고정된 스케줄에 맞춰 진행됩니다: 디코딩이 한 프레임 이상 지연되면 해당 프레임은 늦게 표시되지 않고 폐기되므로, 영상은 실제 시간 속도를 유지합니다.
</Note>

## JPEG로 내보내기

DWVO는 이미 MJPEG를 저장하므로 `export.py`는 각 프레임을 그대로 디스크에 복사합니다 — 디코딩 없음, 품질 손실 없음.

```bash theme={null}
python export.py file.dwvo output-folder

# 5프레임마다 하나씩 유지
python export.py file.dwvo output-folder --step 5
```

| 인수                |                                        |
| ----------------- | -------------------------------------- |
| `--step N`        | N번째 프레임마다 하나씩 유지합니다.                   |
| `--start-frame N` | 첫 출력 인덱스. 이전 시퀀스에서 번호를 이어서 매길 때 사용합니다. |

출력은 카메라별로 하나의 디렉터리에 KITTI 스타일로 번호가 매겨집니다:

```
out/
  image_0/000000.jpg, 000001.jpg, ...
  image_1/000000.jpg, 000001.jpg, ...
  times.txt
```

## 무손실 PNG (KITTI 데이터셋)

`dwvo_to_kitti.py`는 동일한 레이아웃을 생성하지만 Pillow를 통해 디코딩하여 무손실 PNG를 출력할 수 있습니다. 하위 도구가 JPEG를 지원하지 않을 때 사용하고, 그렇지 않다면 `export.py`가 더 빠릅니다.

```bash theme={null}
python dwvo_to_kitti.py test.dwvo out          # PNG
python dwvo_to_kitti.py test.dwvo out --jpeg   # export.py와 동일한 제로 카피 JPEG
```

## 프로그래밍 방식으로 DWVO 읽기

`dwvo.py`에서 `DWVOReader`는 타임스탬프 블록을 반복하고, `DWVOWriter`는 블록을 작성하며, `combine_dwvos()`는 헤더를 공유하는 녹화 파일들을 연결합니다.

```python theme={null}
from pathlib import Path
from dwvo import DWVOReader

with DWVOReader(Path("test.dwvo")) as reader:
    print(reader.header.n_cameras, reader.header.width, reader.header.height)
    for block in reader.iter_blocks():
        for frame in block.video_frames:   # one per camera
            frame.bus_id, frame.data       # "0" / "1", raw JPEG bytes
```

## 자주 묻는 질문

<AccordionGroup>
  <Accordion title="녹화한 영상보다 재생 속도가 느린 이유는 무엇인가요?">
    Discovery에서 일부 카메라는 FPS를 수동으로 설정해야 합니다. 영상이 60 FPS로 스트리밍되는 동안 30 FPS로 설정되어 있었다면, `.dwvo` 파일은 메타데이터에 30 FPS를 기록하고 애플리케이션에게 30 FPS로 읽도록 알립니다. 재생 시 `--fps`로 이를 재정의하세요.
  </Accordion>
</AccordionGroup>

## 추가 정보

더 자세한 내용, 다른 언어로 된 예제, 그리고 위 스크립트의 전체 소스는 OpenCV Guides 저장소에서 확인할 수 있습니다.

<Card title="OpenCV Guides 저장소" icon="Github" href="https://github.com/DeepWaterExploration/opencv-guides">
  DWVO 리더, 재생, 내보내기 및 KITTI 변환 소스.
</Card>