SB SDK 1.11
Image

Collection of functions to manage images. More...

Collaboration diagram for Image:

Data Structures

struct  sb_t_rle_seg
 Define a RLE segment. More...
 
struct  sb_t_rle
 Defines a RLE. More...
 
struct  sb_t_image
 Defines an image. More...
 

Macros

#define SB_IMAGE_FILE_EXTENSIONS
 List of the possible extensions of the image.
 

Enumerations

enum  sb_t_image_format { SB_IMAGE_FORMAT_BW8 = 0 , SB_IMAGE_FORMAT_BGR888 , SB_IMAGE_FORMAT_RGB888 , SB_IMAGE_FORMAT_UI32 }
 Format of image pixel. More...
 
enum  sb_t_image_compress_type { SB_IMAGE_COMPRESS_NONE = 0 , SB_IMAGE_COMPRESS_RLE , SB_IMAGE_COMPRESS_JPEG , SB_IMAGE_COMPRESS_PNG }
 Type of image compression. More...
 
enum  sb_t_image_compress_par { SB_IMAGE_COMPRESS_PAR_JPEG_QUALITY = 1 }
 Definitions of parameters used by the image encoders. More...
 
enum  sb_t_image_flip_mode { SB_IMAGE_FLIP_BOTH = -1 , SB_IMAGE_FLIP_HORIZONTAL = 0 , SB_IMAGE_FLIP_VERTICAL = 1 }
 Enumeration of the flip mode. More...
 

Functions

const char * sb_image_format (sb_t_image_format format)
 Returns the string of the image format. More...
 
sb_t_err sb_image_create (sb_t_image **const pimg, int width, int height, sb_t_image_format format)
 Creates an image. More...
 
sb_t_err sb_image_create_header (sb_t_image **const pimg, int width, int height, int width_step, sb_t_image_format format)
 Creates an image but doesn't allocate memory for the data. More...
 
sb_t_err sb_image_destroy (sb_t_image **const pimg)
 Destroys the image. More...
 
sb_t_err sb_image_compress (sb_t_image **const dst, sb_t_image *const src, sb_t_image_compress_type compression, const void *const params)
 Compress the image with the compression method specified. More...
 
sb_t_err sb_image_decompress (sb_t_image **const dst, sb_t_image *const src)
 Decompress the image. More...
 
sb_t_err sb_image_set_clip_blend (sb_t_image *const img, int x, int y, const sb_t_rgba *const color)
 Set the pixel (x,y) with the color using also alpha blending. More...
 
sb_t_err sb_image_get_pixel (sb_t_image *const img, int x, int y, sb_t_rgba *const color)
 Get the pixel (x,y). More...
 
sb_t_err sb_image_set_data (sb_t_image *const img, unsigned char *const data)
 Sets the pointer to a block of memory for image data. More...
 
sb_t_err sb_image_clone (sb_t_image **const dst, const sb_t_image *const src)
 Clones the image. More...
 
sb_t_err sb_image_copy (const sb_t_image *const src, sb_t_image *const dst)
 Copies the image. More...
 
sb_t_err sb_image_copy_rect (const sb_t_image *const src, sb_t_rect rect, sb_t_image **const dst)
 Copies a rectangular ROI of an image into another one. More...
 
sb_t_err sb_image_clean (sb_t_image *const img)
 Cleans the image. More...
 
sb_t_err sb_image_save (const sb_t_image *const img, const char *const file, const int *const params)
 Saves the image in a file. More...
 
sb_t_err sb_image_load (sb_t_image **const img, const char *const file)
 Loads an image from a file. More...
 
sb_t_err sb_image_convert (sb_t_image **const dst, sb_t_image *const src, sb_t_image_format format)
 Convert the source image into the destination image. More...
 
sb_t_err sb_image_flip (const sb_t_image *const src, sb_t_image *const dst, sb_t_image_flip_mode mode)
 Flips the image. More...
 
sb_t_err sb_image_shift (const sb_t_image *const src, sb_t_image *const dst, int x_shift, int y_shift)
 Shifts the image. More...
 
sb_t_err sb_image_rotate (const sb_t_image *const src, sb_t_point centre, double angle, sb_t_interpolation_mode interpolation_mode, sb_t_image *const dst)
 Rotates an image. More...
 
sb_t_err sb_image_resize (const sb_t_image *const src, sb_t_rect rect, float scale, sb_t_interpolation_mode interpolation_mode, sb_t_image *const dst)
 Resizes the image. More...
 
sb_t_err sb_image_get_sample (const sb_t_image *const src, sb_t_point centre, double angle_rad, float scale, sb_t_image *const dst)
 Copies, rotates, resizes a rectangular roi of the source image to the destination one. More...
 
sb_t_err sb_image_change_brightness (const sb_t_image *const src, sb_t_image *const dst, float delta_brightness)
 Changes the image brightness by the percentage amount specified. More...
 
sb_t_err sb_image_change_contrast (const sb_t_image *const src, sb_t_image *const dst, float delta_contrast)
 Changes the image contrast by the percentage amount specified. More...
 

Detailed Description

Collection of functions to manage images.

See Image management for more detailed information about how to handle the images.

Enumeration Type Documentation

◆ sb_t_image_compress_par

Definitions of parameters used by the image encoders.

The values are 32 bits both for 32 and 64 bits library version.

See also
sb_image_compress
sb_image_save
Enumerator
SB_IMAGE_COMPRESS_PAR_JPEG_QUALITY 

Quality of jpeg image.

Definition at line 6738 of file sb.h.

◆ sb_t_image_compress_type

Type of image compression.

The values are 32 bits both for 32 and 64 bits library version.

Enumerator
SB_IMAGE_COMPRESS_NONE 

uncompressed or raw images

SB_IMAGE_COMPRESS_RLE 

RLE (Run Lenght Encoding) lossless compression.

SB_IMAGE_COMPRESS_JPEG 

JPEG compression.

SB_IMAGE_COMPRESS_PNG 

PNG compression.

Definition at line 6626 of file sb.h.

◆ sb_t_image_flip_mode

Enumeration of the flip mode.

The values are 32 bits both for 32 and 64 bits library version.

Enumerator
SB_IMAGE_FLIP_BOTH 

flips the image around both horizontal and vertical axises, it is a rotation of 180 degrees.

SB_IMAGE_FLIP_HORIZONTAL 

flips the image around horizontal axis.

SB_IMAGE_FLIP_VERTICAL 

flips the image around vertical axis.

Definition at line 6928 of file sb.h.

◆ sb_t_image_format

Format of image pixel.

The values are 32 bits both for 32 and 64 bits library version.

Enumerator
SB_IMAGE_FORMAT_BW8 

BW: one channel, 8 bit per channel.

SB_IMAGE_FORMAT_BGR888 

BGR: three channel, 8 bit per channel.

SB_IMAGE_FORMAT_RGB888 

RGB: three channel, 8 bit per channel.

SB_IMAGE_FORMAT_UI32 

unsigned int 32 bit

Definition at line 6605 of file sb.h.

Function Documentation

◆ sb_image_change_brightness()

sb_t_err sb_image_change_brightness ( const sb_t_image *const  src,
sb_t_image *const  dst,
float  delta_brightness 
)

Changes the image brightness by the percentage amount specified.

Each pixel of the image is changed by adding a value in the range [-255, 255], computed from the delta_brightness percentage specificied.

Parameters
[in]srcPointer to the source image.
[in]dstPointer to the destination image.
[in]delta_brightnessPercentage of brightness variation to apply to the pixels of the image. Valid values [-1.0f, 1.0f].
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_change_contrast()

sb_t_err sb_image_change_contrast ( const sb_t_image *const  src,
sb_t_image *const  dst,
float  delta_contrast 
)

Changes the image contrast by the percentage amount specified.

Each pixel of the image is changed by computing a new value considering the actual image histogram contrast (max - min) and the percentage of the contrast variation specified. Positive percentage values increase the contrast, while negative percentage values reduce the contrast.

Parameters
[in]srcPointer to the source image.
[in]dstPointer to the destination image.
[in]delta_contrastPercentage of contrast variation. Valid values [-1.0f, 1.0f].
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_clean()

sb_t_err sb_image_clean ( sb_t_image *const  img)

Cleans the image.

Parameters
[in,out]imgPointer to the image.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_clone()

sb_t_err sb_image_clone ( sb_t_image **const  dst,
const sb_t_image *const  src 
)

Clones the image.

Parameters
[in,out]dstPointer to the image.
On successful return, this parameter will be updated with the pointer of the image.
[in]srcPointer to the image
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_destroy

◆ sb_image_compress()

sb_t_err sb_image_compress ( sb_t_image **const  dst,
sb_t_image *const  src,
sb_t_image_compress_type  compression,
const void *const  params 
)

Compress the image with the compression method specified.

Attention
RLE Compression type is available only for 8-bit images
Parameters
[out]dstPointer to the destination image, can be NULL if the compression is made on the source image.
[in]srcPointer to the source image
[in]compressionCompression type of the image
[in]paramsOptional parameters.
Actually used only by jpeg compression to set the quality.
If params is NULL the default quality is 95.
Usage example:
int par[3];
par[1] = 90;
par[2] = 0;
sb_t_err sb_image_compress(sb_t_image **const dst, sb_t_image *const src, sb_t_image_compress_type compression, const void *const params)
Compress the image with the compression method specified.
@ SB_IMAGE_COMPRESS_JPEG
JPEG compression.
Definition: sb.h:6630
@ SB_IMAGE_COMPRESS_PAR_JPEG_QUALITY
Quality of jpeg image.
Definition: sb.h:6740
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_create
sb_image_create_header
sb_image_decompress
sb_t_image_compress_par

◆ sb_image_convert()

sb_t_err sb_image_convert ( sb_t_image **const  dst,
sb_t_image *const  src,
sb_t_image_format  format 
)

Convert the source image into the destination image.

Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[out]dstPointer to the destination image.
If equal to src the function operates in place.
. If the pointer to destination image (*dst) is NULL the destination image is created.
[in]formatDestination image format. The parameter is used only if destination image is created.
Only the following formats are possible:
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_destroy

◆ sb_image_copy()

sb_t_err sb_image_copy ( const sb_t_image *const  src,
sb_t_image *const  dst 
)

Copies the image.

Parameters
[in]srcPointer to the source image.
[out]dstPointer to the destination image.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_destroy

◆ sb_image_copy_rect()

sb_t_err sb_image_copy_rect ( const sb_t_image *const  src,
sb_t_rect  rect,
sb_t_image **const  dst 
)

Copies a rectangular ROI of an image into another one.

Borders are replicated if the ROI is out of the image.

Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[in]rectCoordinates of the rectangle ROI.
[out]dstPointer to the destination image.
If the value of dst is NULL the image is allocated.
If the value is not NULL the function verifies that the width and height of the image and the rect are equal, furthermore it verifies that the format of the src and dst image are the same.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_create()

sb_t_err sb_image_create ( sb_t_image **const  pimg,
int  width,
int  height,
sb_t_image_format  format 
)

Creates an image.

Parameters
[out]pimgPointer to the image.
On successful return, this parameter will be updated with the pointer of the image.
[in]widthWidth, in pixel, of the image.
[in]heightHeight, in pixel, of the image.
[in]formatImage format.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_create_header
sb_image_destroy

◆ sb_image_create_header()

sb_t_err sb_image_create_header ( sb_t_image **const  pimg,
int  width,
int  height,
int  width_step,
sb_t_image_format  format 
)

Creates an image but doesn't allocate memory for the data.

The user should use the function sb_image_set_data to assign a block on memory for image data.
The block of memory must have a greater or equal than height * width_step.

Parameters
[out]pimgPointer to the image.
On successful return, this parameter will be updated with the pointer of the handle.
[in]widthWidth, in pixel, of the image.
[in]heightHeight, in pixel, of the image.
[in]width_stepNumber of bytes to move the pointer to one row to the next one.
[in]formatImage format.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_create
sb_image_destroy
sb_image_set_data

◆ sb_image_decompress()

sb_t_err sb_image_decompress ( sb_t_image **const  dst,
sb_t_image *const  src 
)

Decompress the image.

Parameters
[out]dstPointer to the destination image, can be NULL if the decompression is made on the source image.
[in]srcPointer to the source image
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_create
sb_image_create_header
sb_image_compress

◆ sb_image_destroy()

sb_t_err sb_image_destroy ( sb_t_image **const  pimg)

Destroys the image.

Attention
In the case the image has been created with sb_image_create_header the function destroys only the header.
Parameters
[out]pimgPointer to the image, it is set to NULL.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_create
sb_image_create_header

◆ sb_image_flip()

sb_t_err sb_image_flip ( const sb_t_image *const  src,
sb_t_image *const  dst,
sb_t_image_flip_mode  mode 
)

Flips the image.

Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[out]dstPointer to the destination image. It may be equal to the source image.
[in]modeFlip mode.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_rotate
sb_image_resize
sb_image_shift

◆ sb_image_format()

const char * sb_image_format ( sb_t_image_format  format)

Returns the string of the image format.

Interprets the contents of the code and converts it to a C-string containing a human-readable version of the corresponding image format.
The string must not be freed.

Parameters
[in]formatImage format.
Returns
A C-string containing the image format in a human-readable format.

◆ sb_image_get_pixel()

sb_t_err sb_image_get_pixel ( sb_t_image *const  img,
int  x,
int  y,
sb_t_rgba *const  color 
)

Get the pixel (x,y).

The function checks if the point is out of the image.

Attention
The function works only on uncompressed images.
Parameters
[in]imgimage.
[in]xx-coordinate of the pixel.
[in]yy-coordinate of the pixel.
[out]colorValue of the pixel.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_get_sample()

sb_t_err sb_image_get_sample ( const sb_t_image *const  src,
sb_t_point  centre,
double  angle_rad,
float  scale,
sb_t_image *const  dst 
)

Copies, rotates, resizes a rectangular roi of the source image to the destination one.

The width and height of the rectangular roi of the source image are the width and height of the destination image multiplicated by the scale. The function uses bilinear interpolation to rotate and resize data. The functions works correctly even if the roi is out of the image, the pixels at the border are replicated.

Warning
If angle_rad is 0 and scale is 1 the function does the copy from source to destination, without interpolation.
Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[in]centreCentre of the rectangular roi in the source image.
[in]angle_radRotation angle, in radians, clockwise if positive.
[in]scaleScale factor of the source image.
[out]dstPointer to the destination image.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_load()

sb_t_err sb_image_load ( sb_t_image **const  img,
const char *const  file 
)

Loads an image from a file.

This software is based in part on the work of the Independent JPEG Group (https://github.com/LuaDist/libjpeg).

Parameters
[out]imgPointer to the image.
[in]fileFile name.
The admitted file extension are:
  1. bmp
  2. pgm
  3. ppm
  4. png
  5. tiff
  6. jpeg
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_destroy

◆ sb_image_resize()

sb_t_err sb_image_resize ( const sb_t_image *const  src,
sb_t_rect  rect,
float  scale,
sb_t_interpolation_mode  interpolation_mode,
sb_t_image *const  dst 
)

Resizes the image.

Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[in]rectCoordinates of the rectangular ROI of the source image that have to be resized.
[in]scaleScale factor.
If the value is greater than 1, the image size is reduced.
if you need to resize the image with a different scale factor in x and y set the scale to 0. In this case the scale will be calculated internally by the function as follows:
  • scale x = rect.width / dst->width
  • scale y = rect.hidth / dst->height
[in]interpolation_modeInterpolation mode.
[out]dstPointer to the destination image.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_flip
sb_image_rotate
sb_image_shift

◆ sb_image_rotate()

sb_t_err sb_image_rotate ( const sb_t_image *const  src,
sb_t_point  centre,
double  angle,
sb_t_interpolation_mode  interpolation_mode,
sb_t_image *const  dst 
)

Rotates an image.

Destination image pixels falling outside the source image are replicated from the nearest border if mode is equal to SB_INTERPOLATION_MODE_BILINEAR, while they are left black in mode is equal to SB_INTERPOLATION_MODE_NN .

Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[in]centreCoordinates of the rotation centre.
[in]angleRotation angle, in radians, clockwise if positive.
[in]interpolation_modeInterpolation mode. In case of interpolation equal to SB_INTERPOLATION_MODE_NN only SB_IMAGE_FORMAT_BW8 images are allowed.
[out]dstPointer to the destination image. It must be different from source image.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_flip
sb_image_resize
sb_image_shift

◆ sb_image_save()

sb_t_err sb_image_save ( const sb_t_image *const  img,
const char *const  file,
const int *const  params 
)

Saves the image in a file.

The function accepts the following images:

image compression
sb_t_image::compression
admitted file extension
uncompressed images SB_IMAGE_COMPRESS_NONE "bmp", "pgm", "ppm", "jpg", "jpeg", "png"
JPEG compressed images SB_IMAGE_COMPRESS_JPEG "jpg", "jpeg"
PNG compressed images SB_IMAGE_COMPRESS_PNG "png"
Parameters
[in]imgPointer to the image
[in]fileFile name.
The admitted file extension are:
  1. bmp
  2. pgm (only SB_IMAGE_FORMAT_BW8 images)
  3. ppm (only SB_IMAGE_FORMAT_RGB888 or SB_IMAGE_FORMAT_BGR888 images)
  4. jpg
  5. jpeg
  6. png
[in]paramsOptional parameters.
Actually used only by jpeg compression to set the quality.
If params is NULL the default quality is 95.
Usage example:
int par[3];
par[1] = 90;
par[2] = 0;
sb_image_save(img, "dummy.jpg", par);
sb_t_err sb_image_save(const sb_t_image *const img, const char *const file, const int *const params)
Saves the image in a file.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_load
sb_t_image_compress_par

◆ sb_image_set_clip_blend()

sb_t_err sb_image_set_clip_blend ( sb_t_image *const  img,
int  x,
int  y,
const sb_t_rgba *const  color 
)

Set the pixel (x,y) with the color using also alpha blending.

The function checks if the point is out of the image.

Attention
The function works only on uncompressed images.
Parameters
[in,out]imgimage.
[in]xx-coordinate of the pixel.
[in]yy-coordinate of the pixel.
[in]colorcolor to draw the pixel.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.

◆ sb_image_set_data()

sb_t_err sb_image_set_data ( sb_t_image *const  img,
unsigned char *const  data 
)

Sets the pointer to a block of memory for image data.

Attention
Function sb_image_destroy will not deallocate the data pointer.
Parameters
[in]imgPointer to the image.
[in]dataPointer of the block of data. The block of memory must have a size greater or equal than height * width_step.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_create_header

◆ sb_image_shift()

sb_t_err sb_image_shift ( const sb_t_image *const  src,
sb_t_image *const  dst,
int  x_shift,
int  y_shift 
)

Shifts the image.

Attention
The function works only on uncompressed images.
Parameters
[in]srcPointer to the source image.
[out]dstPointer to the destination image. It may be equal to the source image.
[in]x_shiftShift along x axis.
[in]y_shiftShift along y axis.
Returns
If successful, returns SB_ERR_NONE. Otherwise, it returns an error code sb_t_err.
See also
sb_image_rotate
sb_image_flip
sb_image_resize