# `NONAI2D CSC` API Manual

## Overview

The K230 chip has 24 built-in hardware Color Space Conversion (CSC) channels, which can efficiently perform image color space conversions. This module supports various image format conversions including common formats such as RGB/YUV, making it suitable for video processing, image display, and similar applications.

## API Reference

### Constructor

**Function**
Initialize a CSC conversion channel. The channel number is automatically allocated by the system.

**Syntax**

```python
from nonai2d import CSC
csc = CSC(fmt, max_width=1920, max_height=1080, buf_num=2)
```

**Parameter Description**

| Parameter    | Type | Description                                                                 | Default  |
|--------------|------|-----------------------------------------------------------------------------|----------|
| fmt          | int  | Target image format (see constant definitions)                               | Required |
| max_width    | int  | Maximum image width supported (in pixels)                                    | 1920     |
| max_height   | int  | Maximum image height supported (in pixels)                                   | 1080     |
| buf_num      | int  | Number of VB buffers allocated, affects processing performance               | 2        |

**Return Value**
Returns a CSC object on success, raises an exception on failure.

> **Important Notes**
>
> 1. The channel number is automatically allocated by the system (range 0-23); users do not need to and cannot specify it
> 1. It is recommended to set `max_width`/`max_height` according to actual image size to save memory
> 1. When `fmt=PIXEL_FORMAT_GRAYSCALE`, the internal pipeline converts to YUV420SP first and then extracts the grayscale channel

**Properties**

| Property  | Type | Description                    |
|-----------|------|--------------------------------|
| `chn`     | int  | Auto-allocated CSC channel number |
| `dst_fmt` | int  | Target image format            |

### `convert` Method

**Function**
Perform image color space conversion

**Syntax**

```python
result = csc.convert(frame, timeout_ms=1000, cvt=True)
```

**Parameter Description**

| Parameter     | Type                | Description                                                          | Default |
|---------------|---------------------|----------------------------------------------------------------------|---------|
| frame         | py_video_frame_info | Input image frame (from `Sensor.snapshot`)                           | Required|
| timeout_ms    | int                 | Conversion timeout in milliseconds                                   | 1000    |
| cvt           | bool                | `True` returns an `Image` object, `False` returns `py_video_frame_info` | True    |

**Return Value**
Returns a converted `Image` object or `py_video_frame_info`, depending on the `cvt` parameter.

### `get_frame` Method

**Function**
Get a converted frame from the CSC channel (low-level interface, does not automatically convert to `Image`).

**Syntax**

```python
frame = csc.get_frame(timeout_ms=1000)
```

**Parameter Description**

| Parameter     | Type | Description                       | Default |
|---------------|------|-----------------------------------|---------|
| timeout_ms    | int  | Timeout in milliseconds           | 1000    |

**Return Value**
Returns a `py_video_frame_info` object on success, `None` on timeout.

> **Note**: Frames obtained via `get_frame` must be manually released using `release_frame`.

### `release_frame` Method

**Function**
Release a frame obtained via `get_frame`.

**Syntax**

```python
csc.release_frame(frame)
```

**Parameter Description**

| Parameter     | Type                | Description              |
|---------------|---------------------|--------------------------|
| frame         | py_video_frame_info | The frame object to release |

### `destroy` Method

**Function**
Release CSC channel resources

**Syntax**

```python
csc.destroy()
```

**Description**
After calling this method, all resources used by the CSC channel will be released, and the object can no longer be used.

## Constant Definitions

### Image Format Constants

| Constant Name                     | Description                          | Typical Use Case              |
|-----------------------------------|--------------------------------------|-------------------------------|
| PIXEL_FORMAT_GRAYSCALE            | Grayscale image format               | Black-and-white image processing |
| PIXEL_FORMAT_RGB_565              | RGB565 format (big-endian)           | LCD display                   |
| PIXEL_FORMAT_RGB_565_LE           | RGB565 format (little-endian)        | Special display devices       |
| PIXEL_FORMAT_BGR_565              | BGR565 format (big-endian)           | OpenCV compatibility          |
| PIXEL_FORMAT_BGR_565_LE           | BGR565 format (little-endian)        | Special display devices       |
| PIXEL_FORMAT_RGB_888              | RGB888 format                        | High-quality image processing |
| PIXEL_FORMAT_BGR_888              | BGR888 format                        | OpenCV compatibility          |
| PIXEL_FORMAT_ARGB_8888            | ARGB8888 format (with transparency)  | GUI composition               |
| PIXEL_FORMAT_ARGB_1555            | ARGB1555 format (with transparency)  | Low color-depth UI            |
| PIXEL_FORMAT_ARGB_4444            | ARGB4444 format (with transparency)  | Low color-depth UI            |
| PIXEL_FORMAT_BGR_888_PLANAR       | BGR888 planar format                 | Professional image processing |
| PIXEL_FORMAT_RGB_888_PLANAR       | RGB888 planar format                 | Professional image processing |
| PIXEL_FORMAT_YVU_PLANAR_420       | YVU420 planar format                 | Video decoding output         |
| PIXEL_FORMAT_YUV_SEMIPLANAR_420   | YUV420 semi-planar format            | Video encoding input          |
| PIXEL_FORMAT_YVU_SEMIPLANAR_420   | YVU420 semi-planar format            | Video processing              |
| PIXEL_FORMAT_YVU_PLANAR_444       | YVU444 planar format                 | High-quality video processing |
| PIXEL_FORMAT_YUV_PACKAGE_444      | YUV444 packed format                 | High-quality video processing |
| PIXEL_FORMAT_YUV_SEMIPLANAR_444   | YUV444 semi-planar format            | High-quality video processing |
| PIXEL_FORMAT_YVU_SEMIPLANAR_444   | YVU444 semi-planar format            | High-quality video processing |

## Best Practice Example

```python
import time, os, urandom, sys

from media.display import *
from media.media import *
from media.uvc import *

from nonai2d import CSC

DISPLAY_WIDTH = ALIGN_UP(800, 16)
DISPLAY_HEIGHT = 480

# hardware Color Space Converter (channel auto-allocated)
csc = CSC(CSC.PIXEL_FORMAT_RGB_565)

# use lcd as display output
Display.init(Display.ST7701, width = DISPLAY_WIDTH, height = DISPLAY_HEIGHT, to_ide = True)

while True:
    plugin, dev = UVC.probe()
    if plugin:
        print(f"detect USB Camera {dev}")
        break
    time.sleep_ms(100)

mode = UVC.video_mode(640, 480, UVC.FORMAT_MJPEG, 30)

succ, mode = UVC.select_video_mode(mode)
print(f"select mode success: {succ}, mode: {mode}")

UVC.start(cvt = True)

clock = time.clock()

while True:
    clock.tick()

    img = UVC.snapshot()
    if img is not None:
        img = csc.convert(img)
        Display.show_image(img)

    print(clock.fps())

# deinit display
Display.deinit()
csc.destroy()
UVC.stop()

time.sleep_ms(100)
```