# VICAP Sensor Demo

## Overview

The `sample_vicap_sensor` demo shows how to use the K230 VICAP (Video Capture) module for camera image capture and display. The VICAP module supports multiple camera sensors and can be used for video input, frame capture, and dump operations.

## Functional Description

### VICAP Features

This sample demonstrates the main VICAP capabilities:

- automatic camera detection and sensor initialization
- real-time image capture
- custom sensor resolution and frame-rate configuration
- automatic aspect-ratio adaptation so the image is not stretched on screen
- dual-channel output:
  - `CHN0` for dump, with `YUV`, `RGB`, and `RAW` formats
  - `CHN1` for preview display in `YUV420SP`
- automatic and manual exposure control in microseconds
- auto white balance (AWB)
- HDR support
- 3D noise reduction (`DNR3`), enabled by default
- dewarp support for image distortion correction

### Supported Parameters

| Parameter | Description | Default |
| --- | --- | --- |
| `-c` | connector type, required | none |
| `-r` | rotation angle (`0/90/180/270`) | `0` |
| `-s` | CSI index (`0-2`) | `2` |
| `-ae` | AE status (`0`: disable, `1`: enable) | `1` |
| `-awb` | AWB status (`0`: disable, `1`: enable) | `1` |
| `-hdr` | HDR status (`0`: disable, `1`: enable) | `0` |
| `-dw` | dewarp status (`0`: disable, `1`: enable) | `0` |
| `-exp` | manual exposure time in microseconds | - |
| `-width` | sensor width | `1920` |
| `-height` | sensor height | `1080` |
| `-fps` | sensor frame rate | `30` |
| `-ofmt` | `CHN0` output format (`0:YUV`, `1:RGB888`, `2:RGB888P`, `3:RAW`) | `0` |
| `-dnr3` | `DNR3` status (`0`: disable, `1`: enable) | `1` |
| `-again` | manual analog gain, requires `-ae 0` | - |

### Interactive Commands

After the program starts, the following commands are available:

| Command | Description |
| --- | --- |
| `d` | dump one frame from `CHN0` |
| `d <n>` | dump `n` frames from `CHN0` |
| `q` | quit the program |

## Source Location

```shell
src/rtsmart/examples/mpp/sample_vicap_sensor/
```

Main file:

- `sample_vicap_sensor.c` - main program source

## Usage

### Build

In the `K230 RTOS SDK` root, use `make menuconfig` to enable the VICAP Sensor sample in the firmware, then rebuild the firmware.

### Run Examples

#### Basic Preview

```shell
./sample_vicap_sensor.elf -c 20
```

#### Custom Resolution and Frame Rate

```shell
./sample_vicap_sensor.elf -c 20 -width 1280 -height 720 -fps 60
```

#### Enable `CHN0` Dump in YUV Format

```shell
./sample_vicap_sensor.elf -c 20 -ofmt 0
```

#### Manual Exposure

```shell
# set exposure to 10000 microseconds (10 ms), AE must be disabled
./sample_vicap_sensor.elf -c 20 -ae 0 -exp 10000
```

#### Manual Gain

```shell
# set gain to 1.0, AE must be disabled
./sample_vicap_sensor.elf -c 20 -ae 0 -again 1.0
```

#### Disable `DNR3`

```shell
./sample_vicap_sensor.elf -c 20 -dnr3 0
```

#### Rotated Display

```shell
# rotate by 90 degrees
./sample_vicap_sensor.elf -c 20 -r 90
```

### Interactive Operation

After startup, the command menu looks like:

```text
Preview running.
CHN0: dump (format=0), CHN1: preview
Commands: d=dump 1 frame, d <n>=dump n frames, q=quit

---------------------------------------
 Input command:
   d      - Dump one frame
   d <n>  - Dump n frames
   q      - Quit
---------------------------------------
Command:
```

Enter `d` or `d 5` to dump images to files.

### Expected Result

At runtime, the program will:

- detect and initialize the camera sensor
- query the sensor resolution and exposure range
- calculate the output size according to the screen aspect ratio
- configure VICAP dual channels, with `CHN0` for dump and `CHN1` for preview
- bind VICAP to the VO display layer
- start image capture and display

Representative output:

```text
INFO: Sensor resolution: 1920x1080
INFO: Sensor fd = 5
sample_vicap_sensor: connector=20, screen_size=1920x1080, output_size=1920x1080, layer=1, rotate=0, csi=2
Aspect ratio mode: sensor=1.78, screen=1.78
CHN0 format: 0 (0=yuv, 1=rgb888, 2=rgb888p, 3=raw)
Fullscreen mode (offset_x=0, offset_y=0)
VICAP features: AE=1, AWB=1, HDR=0, Dewarp=0, DNR3=1, Again=1.00
Bind VICAP(dev=0, ch=1) -> VO(layer=1) OK
Starting VICAP stream on dev0 ch0 ...
INFO: Manual exposure set to 10000 us (0.010000 sec), range: 0.000030-0.033333 sec
Preview running.
CHN0: dump (format=0), CHN1: preview
Commands: d=dump 1 frame, d <n>=dump n frames, q=quit
```

Dump files are saved with names like:

```shell
vicap_dev0_chn0_1920x1080_0000.yuv420sp
vicap_dev0_chn0_1920x1080_0001.yuv420sp
...
```

```{admonition} Tip
- When configuring manual exposure, disable AE first with `-ae 0`.
- Exposure values must be within the sensor-supported range; the program checks and prints the valid range automatically.
- `CHN0` is used for dump and supports multiple formats; `CHN1` is used for preview and is fixed to `YUV420SP`.
- The output resolution is adjusted automatically according to the screen aspect ratio to avoid stretching.
```

```{admonition} Notes
- When using `-exp`, you must also set `-ae 0`.
- When using `-again`, you must also set `-ae 0`.
- The exposure unit is microseconds (`us`), for example `10000` means `10 ms`.
- The gain range depends on the sensor and is checked by the program.
- Dump is triggered by interactive commands, not a command-line option.
- Width is automatically aligned to a multiple of 8 as required by the hardware.
```

## Related Documentation

- [Sensor API documentation](../../api_reference/mpp/sensor.md)
- [VICAP API documentation](../../api_reference/mpp/vicap.md)
- [Display documentation](./display.md)