Skip to main content

​
Overview

Provides fundamental image operations including creation, destruction, sampling, cropping, and distance transforms. Supports multiple image formats with different data types.

​
Types

​
StitchPoint

Represents a 2D point in image space. 
typedef struct {
    int x;
    int y;
} StitchPoint;
​
x
int
Horizontal coordinate
​
y
int
Vertical coordinate

​
StitchRect

Represents a rectangular region in image space. 
typedef struct {
    int x;
    int y;
    int width;
    int height;
} StitchRect;
​
x
int
Left edge x-coordinate
​
y
int
Top edge y-coordinate
​
width
int
Rectangle width in pixels
​
height
int
Rectangle height in pixels

​
ImageType

Enumeration of image data types. 
typedef enum {
    IMAGE,    // unsigned char
    IMAGES,   // short
    IMAGEF    // float
} ImageType;

​
Functions

​
create_image

Loads an image from a file. 
Image create_image(const char *filename);
​
filename
const char*
required
Path to the image file (typically JPEG)
​
return
Image
Loaded image structure with allocated data buffer

​
Example

Image img = create_image("photo.jpg");
if (img.data != NULL) {
    printf("Loaded %dx%d image with %d channels\n", 
           img.width, img.height, img.channels);
}

​
create_empty_image

Creates an empty image with allocated buffer. 
Image create_empty_image(int width, int height, int channels);
​
width
int
required
Image width in pixels
​
height
int
required
Image height in pixels
​
channels
int
required
Number of color channels (typically 1 for grayscale, 3 for RGB)
​
return
Image
Newly allocated empty image (unsigned char data)

​
create_empty_image_s

Creates an empty short integer image. 
ImageS create_empty_image_s(int width, int height, int channels);
​
width
int
required
Image width in pixels
​
height
int
required
Image height in pixels
​
channels
int
required
Number of color channels
​
return
ImageS
Newly allocated empty image (short data)

​
create_empty_image_f

Creates an empty floating-point image. 
ImageF create_empty_image_f(int width, int height, int channels);
​
width
int
required
Image width in pixels
​
height
int
required
Image height in pixels
​
channels
int
required
Number of color channels
​
return
ImageF
Newly allocated empty image (float data)

​
destroy_image

Frees memory allocated for an unsigned char image. 
void destroy_image(Image *img);
​
img
Image*
required
Pointer to image to destroy
Always call this to prevent memory leaks after you’re done with an Image.

​
destroy_image_s

Frees memory allocated for a short integer image. 
void destroy_image_s(ImageS *img);
​
img
ImageS*
required
Pointer to short image to destroy

​
destroy_image_f

Frees memory allocated for a floating-point image. 
void destroy_image_f(ImageF *img);
​
img
ImageF*
required
Pointer to float image to destroy

​
upsample

Upsamples an unsigned char image by a given factor. 
Image upsample(Image *img, float upsample_factor);
​
img
Image*
required
Pointer to source image
​
upsample_factor
float
required
Scale factor (e.g., 2.0 doubles dimensions)
​
return
Image
Newly allocated upsampled image
The returned image has new dimensions: width × upsample_factor and height × upsample_factor.

​
upsample_image_s

Upsamples a short integer image. 
ImageS upsample_image_s(ImageS *img, float upsample_factor);
​
img
ImageS*
required
Pointer to source short image
​
upsample_factor
float
required
Scale factor
​
return
ImageS
Newly allocated upsampled short image

​
upsample_image_f

Upsamples a floating-point image. 
ImageF upsample_image_f(ImageF *img, float upsample_factor);
​
img
ImageF*
required
Pointer to source float image
​
upsample_factor
float
required
Scale factor
​
return
ImageF
Newly allocated upsampled float image

​
downsample

Downsamples an unsigned char image by factor of 2. 
Image downsample(Image *img);
​
img
Image*
required
Pointer to source image
​
return
Image
Newly allocated downsampled image (half dimensions)
Uses Gaussian smoothing before downsampling to prevent aliasing.

​
downsample_s

Downsamples a short integer image by factor of 2. 
ImageS downsample_s(ImageS *img);
​
img
ImageS*
required
Pointer to source short image
​
return
ImageS
Newly allocated downsampled short image

​
downsample_f

Downsamples a floating-point image by factor of 2. 
ImageF downsample_f(ImageF *img);
​
img
ImageF*
required
Pointer to source float image
​
return
ImageF
Newly allocated downsampled float image

​
crop_image

Crops an image in-place by removing borders. 
void crop_image(Image *img, int cut_top, int cut_bottom, int cut_left, int cut_right);
​
img
Image*
required
Pointer to image to crop (modified in-place)
​
cut_top
int
required
Number of pixels to remove from top
​
cut_bottom
int
required
Number of pixels to remove from bottom
​
cut_left
int
required
Number of pixels to remove from left
​
cut_right
int
required
Number of pixels to remove from right
This modifies the image structure in-place. The original data buffer is freed and replaced.

​
Example

Image img = create_image("photo.jpg");
// Remove 10 pixels from each edge
crop_image(&img, 10, 10, 10, 10);
printf("Cropped to %dx%d\n", img.width, img.height);

​
distance_transform

Applies distance transform to a mask image. 
void distance_transform(Image *mask);
​
mask
Image*
required
Pointer to binary mask image (modified in-place)
Converts binary mask to distance field where each pixel’s value represents distance to nearest zero pixel. Useful for creating smooth blending weights.

​
Example

Image mask = create_mask(640, 480, 0.1f, 0, 1);
distance_transform(&mask);
// Mask now contains distance values instead of binary 0/255

​
create_image_mask

Creates a horizontal gradient mask for blending. 
Image create_image_mask(int width, int height, float range, int left, int right);
​
width
int
required
Mask width in pixels
​
height
int
required
Mask height in pixels
​
range
float
required
Gradient transition range as fraction of width (0.0-1.0)
​
left
int
required
Value for left side (0 or 1)
​
right
int
required
Value for right side (0 or 1)
​
return
Image
Grayscale gradient mask image
Creates a horizontal gradient from left to right. The range parameter controls the width of the transition zone.

​
Example

// Create mask: white on left, black on right, 10% transition
Image mask1 = create_image_mask(1024, 768, 0.1f, 1, 0);

// Create mask: black on left, white on right, 10% transition  
Image mask2 = create_image_mask(1024, 768, 0.1f, 0, 1);

​
save_image

Saves an image to disk as JPEG. 
int save_image(const Image *img, const char *out_filename);
​
img
const Image*
required
Pointer to image to save
​
out_filename
const char*
required
Output file path
​
return
int
1 on success, 0 on failure

​
Example

if (save_image(&img, "output.jpg")) {
    printf("Image saved successfully\n");
}

​
image_size

Calculates total size in bytes of an unsigned char image. 
int image_size(Image *img);
​
img
Image*
required
Pointer to image
​
return
int
Total bytes (width × height × channels)

​
image_size_s

Calculates total size in bytes of a short image. 
int image_size_s(ImageS *img);
​
img
ImageS*
required
Pointer to short image
​
return
int
Total bytes (width × height × channels × sizeof(short))

​
image_size_f

Calculates total size in bytes of a float image. 
int image_size_f(ImageF *img);
​
img
ImageF*
required
Pointer to float image
​
return
int
Total bytes (width × height × channels × sizeof(float))

​
Usage Example

#include "image_operations.h"

void process_image() {
    // Load image
    Image img = create_image("input.jpg");
    
    // Create a working copy
    Image working = create_empty_image(img.width, img.height, img.channels);
    memcpy(working.data, img.data, image_size(&img));
    
    // Crop borders
    crop_image(&working, 50, 50, 50, 50);
    
    // Downsample
    Image small = downsample(&working);
    
    // Upsample back
    Image large = upsample(&small, 2.0f);
    
    // Save result
    save_image(&large, "processed.jpg");
    
    // Cleanup
    destroy_image(&img);
    destroy_image(&working);
    destroy_image(&small);
    destroy_image(&large);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us