> ## 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.

# Leitura de gravações DWVO

> Reproduza, exporte e analise gravações .dwvo com Python e OpenCV.

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

<Tooltip tip="DeepWater Video Object">`.dwvo`</Tooltip> é o nosso contêiner de gravação multi-câmera, produzido quando você grava no Discovery. O payload é MJPEG, então cada quadro do arquivo já é um JPEG completo — a reprodução é uma única chamada `cv2.imdecode`, e a exportação é uma cópia de bytes sem recodificação nem perda de qualidade.

<Card title="Gravando DWVO no Discovery" icon="video" href="/pt/discovery/misc/dwvo-support" horizontal>
  Novo no DWVO? Comece por aqui para transmitir e gravar arquivos `.dwvo`.
</Card>

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

## Pré-requisitos

* Python (versão 3.x)
* `opencv-python`, `numpy` e `pillow`
* Uma gravação `.dwvo` — os exemplos abaixo usam `test.dwvo`

## Configuração

Clone o repositório OpenCV Guides e abra a pasta deste guia, depois crie um ambiente virtual e instale as dependências:

<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>

## Reprodução

`main.py` decodifica todas as câmeras e as exibe lado a lado em uma única janela do OpenCV.

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

| Argumento / tecla |                                                    |
| ----------------- | -------------------------------------------------- |
| `--fps N`         | Taxa de reprodução. O padrão é o fps do cabeçalho. |
| `--loop`          | Recomeça ao chegar ao fim do arquivo.              |
| `space`           | Pausar / retomar.                                  |
| `q` / `esc`       | Sair.                                              |

<Note>
  A reprodução é ancorada a um cronograma fixo: se a decodificação atrasar um quadro inteiro, esse quadro é descartado em vez de exibido atrasado, para que o vídeo se mantenha na velocidade real.
</Note>

## Exportar para JPEGs

Como o DWVO já armazena MJPEG, `export.py` copia cada quadro diretamente para o disco — sem decodificação e sem perda de qualidade.

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

# manter apenas um a cada cinco quadros
python export.py file.dwvo output-folder --step 5
```

| Argumento         |                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `--step N`        | Mantém a cada N-ésimo quadro.                                                            |
| `--start-frame N` | Primeiro índice de saída, para continuar a numeração a partir de uma sequência anterior. |

A saída é um diretório por câmera, numerado no estilo KITTI:

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

## PNG sem perdas (dataset KITTI)

`dwvo_to_kitti.py` produz o mesmo layout, mas decodifica através do Pillow para poder gerar PNG sem perdas. Use-o quando uma ferramenta downstream não aceitar JPEG; caso contrário, `export.py` é mais rápido.

```bash theme={null}
python dwvo_to_kitti.py test.dwvo out          # PNG
python dwvo_to_kitti.py test.dwvo out --jpeg   # mesmo JPEG zero-copy do export.py
```

## Lendo DWVO programaticamente

Em `dwvo.py`, `DWVOReader` itera sobre blocos de timestamp, `DWVOWriter` os escreve e `combine_dwvos()` concatena gravações que compartilham o mesmo cabeçalho.

```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
```

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Por que o vídeo está mais lento do que o que gravei?">
    No Discovery, algumas câmeras exigem que o FPS seja definido manualmente. Se foi definido como 30 FPS enquanto o vídeo era transmitido a 60 FPS, o arquivo `.dwvo` registra 30 FPS em seus metadados e informa às aplicações para ler a 30 FPS. Substitua isso na reprodução com `--fps`.
  </Accordion>
</AccordionGroup>

## Informações adicionais

Para mais detalhes, exemplos em outras linguagens e o código-fonte completo dos scripts acima, consulte o repositório OpenCV Guides.

<Card title="Repositório OpenCV Guides" icon="Github" href="https://github.com/DeepWaterExploration/opencv-guides">
  Código-fonte do leitor DWVO, reprodução, exportação e conversão para KITTI.
</Card>