5.10.3. GDC Bin API
5.10.3.1. Module Description
The GDC bin API guides how to generate GDC bin files.
The GDC bin API generates GDC bin files via the
hbn_gen_gdc_bin_jsonorhbn_gen_gdc_bininterfaces, and releases the GDC bin buffer usinghbn_free_gdc_bin.The GDC bin API is typically used in conjunction with the simulation tool GDC Tool. All transformation modes in GDC Tool can generate a
layout.jsonfile, which can then be used by the GDC Bin API to produce a GDC bin file.
For instructions on using GDC Tool, refer to GDC Tool Introduction.
Operation Flow
The general process for using the GDC Bin API:
First, use GDC Tool to generate a JSON file, then use
hbn_gen_gdc_bin_jsonto generate a GDC bin file. See example generate_bin.Load the generated GDC bin file into memory allocated by hbmem, then configure it to the GDC node via
hbn_vnode_set_attr.Start the GDC node: begin image processing, and save the processed data to the file system using
dump_2plane_yuv_to_file.After processing completes, release the buffer storing the GDC bin using
hbn_free_gdc_bin.
For custom transformations, target images and calibration parameters must be generated in advance. Refer to the example custom-config to generate calibration parameters before continuing with the above steps.
5.10.3.2. Reference Examples
Example code for GDC can be found in the sample_gdc section.
5.10.3.3. API Reference
The following APIs are used for GDC BIN generation. For GDC module control APIs, see GDC API.
| API Interface | Functionality |
|---|---|
| hbn_gen_gdc_bin | Configures and generates a gdc bin file using window parameters, storing it in cfg_buf; the size of this binary data is stored in cfg_size |
| hbn_gen_gdc_bin_json | Reads a JSON configuration file, parses its content, generates a binary gdc bin file, and writes it to a specified file |
| hbn_free_gdc_bin | Frees the buffer allocated by hbn_gen_gdc_bin() or hbn_gen_gdc_bin_json() for storing the gdc bin |
hbn_gen_gdc_bin
【Function Declaration】
int32_t hbn_gen_gdc_bin(const param_t *gdc_param, const window_t *windows, uint32_t wnd_num, uint32_t **cfg_buf, uint64_t *cfg_size);
【Function Description】
Generates a gdc bin file using window configuration, stores it in cfg_buf, and writes the size of this binary data into cfg_size.
【Parameter Description】
[IN] param_t *gdc_parm: GDC-related parameters including resolution, format, etc.
[IN] window_t *wnds: Internal region parameters of GDC.
[IN] uint32_t wnd_num: Number of windows.
[OUT] uint32_t **cfg_buf: Generated gdc cfg bin, internally allocated.
[OUT] uint64_t *cfg_size: Size of the gdc cfg bin file.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
hbn_gen_gdc_bin_json
【Function Declaration】
int32_t hbn_gen_gdc_bin_json(const char *layout_file, char *config_file, uint32_t **cfg_buf, uint64_t *config_size);
【Function Description】
Reads a JSON configuration file, parses its content, generates a binary gdc bin file, and writes it to a specified file.
【Parameter Description】
[IN] const char *layout_file: Path to the JSON file containing parameters for generating the gdc bin.
[IN] char *config_file: Specifies a file path where the generated gdc bin will be stored; can be NULL.
[OUT] uint32_t **cfg_buf: Generated gdc cfg bin, internally allocated.
[OUT] uint64_t *cfg_size: Size of the gdc cfg bin file.
【Return Value】
Success: HBN_STATUS_SUCCESS 0.
Failure: Negative error code, refer to Return Value Description.
【Compatibility】
Hardware: X5
hbn_free_gdc_bin
【Function Declaration】
void hbn_free_gdc_bin(uint32_t *cfg_buf);
【Function Description】
Frees the buffer allocated by hbn_gen_gdc_bin() or hbn_gen_gdc_bin_json() for storing the gdc bin.
【Parameter Description】
[IN] uint32_t *cfg_buf: Buffer address of the gdc bin.
【Return Value】
None.
【Compatibility】
Hardware: X5
5.10.3.4. Data Structures
typedef struct param_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| format | frame_format_t | - | - | - | Image processing format | Yes |
| in | resolution_t | - | - | - | Actual input image dimensions | Yes |
| out | resolution_t | - | - | - | Actual output image dimensions | Yes |
| x_offset | int32_t | 0 | - | 0 | Pixel offset of input region along x-axis | Yes |
| y_offset | int32_t | 0 | - | 0 | Pixel offset of input region along y-axis | Yes |
| diameter | int32_t | 0 | Pixel diameter of the circular region within the rectangular input image that contains the actual fisheye image. For some cameras, this circular region's diameter may be larger or smaller than the rectangular canvas (sometimes cropped). Typically, diameter should match input.height | Yes | ||
| fov | double | 0 | Field of view defines the visible angle of the input image, affecting source grid curvature. Larger FOV results in greater perspective distortion | Yes |
typedef enum frame_format frame_format_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| FMT_UNKNOWN | - | - | - | - | Unknown format | - |
| FMT_LUMINANCE | - | - | - | - | Not supported | - |
| FMT_PLANAR_444 | - | - | - | - | Not supported | - |
| FMT_PLANAR_420 | - | - | - | - | Not supported | - |
| FMT_SEMIPLANAR_420 | - | - | - | - | nv12 | - |
| FMT_GDC_MAX | - | - | - | - | - | - |
typedef struct resolution_s resolution_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| w | uint32_t | - | - | - | Width (pixels) | - |
| h | uint32_t | - | - | - | Height (pixels) | - |
typedef struct window_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| out_r | rect_t | - | - | - | Output data size information | - |
| transform | transformation_t | 0 | 6 | 0 | Transformation mode used | - |
| input_roi_r | rect_t | ROI area | ||||
| pan | int32_t | Horizontal target displacement centered on output image (in pixels) | ||||
| tilt | int32_t | Vertical target displacement centered on output image (in pixels) | ||||
| zoom | double | Target scaling factor | ||||
| strength | double | 1.0 | Non-negative transformation intensity in x-direction | |||
| strengthY | double | 1.0 | Non-negative transformation intensity in y-direction | |||
| angle | double | 0 | Rotation angle of the main projection axis around itself | |||
| elevation | double | 0 | Angle specifying the main projection axis | |||
| azimuth | double | 0 | Angle specifying the main projection axis, measured clockwise from north | |||
| keep_ratio | int32_t | 1 | Maintain equal stretch intensity in horizontal and vertical directions | |||
| FOV_h | double | 90 | Vertical dimension of output field of view in degrees | |||
| FOV_w | double | 90 | Horizontal dimension of output field of view in degrees | |||
| cylindricity_y | double | 0 | Cylindricity level of projection shape in vertical direction | |||
| cylindricity_x | double | 0 | Cylindricity level of projection shape in horizontal direction | |||
| custom_file[128] | char | Custom transformation description file in custom mode | ||||
| custom | custom_tranformation_t | Transformation information in custom mode | ||||
| trapezoid_left_angle | double | 0 | Left acute angle between trapezoid base and slanted side | |||
| trapezoid_right_angle | double | 0 | Right acute angle between trapezoid base and slanted side | |||
| check_compute | uint8_t | Currently unused |
typedef struct rect_s rect_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| x | int32_t | - | - | - | Starting x-coordinate, must be even | - |
| y | int32_t | - | - | - | Starting y-coordinate, must be even | - |
| w | int32_t | Width, must be even | ||||
| h | int32_t | Height, must be even |
typedef enum gdc_transformation transformation_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| PANORAMIC | - | - | - | - | Panoramic transformation | |
| CYLINDRICAL | - | - | - | - | NA | |
| STEREOGRAPHIC | - | - | - | - | Same as distortion correction and panoramic transformation, but output image is a cylindrical panorama rather than a flat image | |
| UNIVERSAL | - | - | - | - | Equidistant transformation | |
| CUSTOM | - | - | - | - | User-defined transformation, allowing customization of transformation grid | |
| AFFINE | - | - | - | - | Linear transformation | |
| DEWARP_KEYSTONE | - | - | - | - | Compared to equidistant transformation, allows non-equidistant; equidistant is just a special case of this |
typedef struct point_s point_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| x | double | - | - | - | x-coordinate | - |
| y | double | - | - | - | y-coordinate | - |
typedef struct custom_tranformation_s custom_tranformation_t
| Name | Type | Min | Max | Default | Meaning | Required |
|---|---|---|---|---|---|---|
| full_tile_calc | uint8_t | - | - | - | Whether to enable tile-based calculation; if enabled, libgdcbin performs additional min/max calculations per tile. More tiles mean higher precision and better results, but longer bin generation time | - |
| tile_incr_x | uint16_t | - | - | - | Tile increment in x direction | - |
| tile_incr_y | uint16_t | - | - | - | Tile increment in y direction | - |
| w | int32_t | Number of points in horizontal direction of custom transformation grid | ||||
| h | int32_t | Number of points in vertical direction of custom transformation grid | ||||
| centerx | double | Center along x-axis, typically half the number of horizontal coordinate points | ||||
| centery | double | Center along y-axis, typically half the number of vertical coordinate points | ||||
| *points | point_t | Transformation sequence from config.txt, count = w*h |