CImg (cimg v0.1.3) View Source

Light-weight image processing module in Elixir with CImg. This module aims to create auxiliary routines for Deep Learning.

Note: It still has a few image processing functions currentrly.

Design detail

The entity of the image handled by CImg is on the NIF side. On Elixir, the reference to the image generated by NIF is stored in the CImg structure. You cannot read out the pixels of the image and process it directly, instead you can use the image processing functions provided in this module.

The image will be assigned to Erlang Resource by NIF, so the image will automatically be subject to garbage collection when it is no longer in use.

This is a very important point. Some of the functions in this module immutably rewrite the original image. I recommend you to make a duplicate of the image before performing the image processing.

Platform

It has been confirmed to work in the following OS environment.

  • Windows MSYS2/MinGW64
  • WSL2/Ubuntu 20.04

Demo

There is a simple program in demo directory. You can do it by following the steps below.

$ cd demo
$ mix deps.get
$ mix run -e "CImgDemo.demo1"

Close the appaired window, and stop the demo program.

Link to this section Summary

Functions

[mut] Assign cimg_src to cimg.

Create image{x,y,z,c} filled val.

Create image{x,y,z,c} from raw binary. create_from_bin helps you to make the image from the serialiezed output tensor of DNN model.

Display the image on the CImgDisplay object.

[mut] Draw filled circle in the image.

Duplicate the image.

[mut] Filling the image with val.

Get the pixel value at (x, y).

Get the gray image of the image.

Get a new image object resized {x, y}.

Load a image from file.

Load a image from memory. You can create an image from loaded binary data of the image file.

[mut] mirroring the image on axis

Save the image to the file.

[mut] Set the pixel value at (x, y).

Get shape {x,y,z,c} of the image

Get byte size of the image

Get serialized binary of the image from top-left to bottom-right. to_flat/2 helps you to make 32bit-float arrary for the input tensors of DNN model.

Link to this section Functions

[mut] Assign cimg_src to cimg.

Parameters

  • cimg - image object.
  • cimg_src - source image to assign

Examples

  iex> res = CImg.assign(imge, image_src)
Link to this function

blur(cimg, sigma, boundary_conditions \\ true, is_gaussian \\ true)

View Source

See CImg.NIF.cimg_blur/4.

Create image{x,y,z,c} filled val.

Parameters

  • x,y,z,c - image's x-size, y-size, z-size and spectrum.
  • val - filling value.

Examples

  iex> img = CImg.create(200, 100, 1, 3, 127)
Link to this function

create_from_bin(bin, x, y, z, c, dtype)

View Source

Create image{x,y,z,c} from raw binary. create_from_bin helps you to make the image from the serialiezed output tensor of DNN model.

Parameters

  • bin - raw binary data to have in a image.
  • x,y,z,c - image's x-size, y-size, z-size and spectrum.
  • dtype - data type in the binary. any data types are converted to int8 in the image.
    • "<f4" - 32bit float (available value in range 0.0..1.0)
    • "<u1" - 8bit unsigned integer

Examples

  iex> bin = TflInterp.get_output_tensor(__MODULE__, 0)
  iex> img = CImg.create_from_bin(bin, 300, 300, 1, 3, "<f4")

Display the image on the CImgDisplay object.

Parameters

  • cimg - image object.
  • display - CImgDisplay object

Examples

  iex> disp = CImgDisplay.create(img, "Sample")
  iex> CImg.display(imge, disp)
Link to this function

draw_circle(cimg, x0, y0, radius, color, opacity \\ 1.0)

View Source

[mut] Draw filled circle in the image.

Parameters

  • cimg - image object.
  • x0,y0 - circle center location
  • radius - circle radius
  • color - filling color
  • opacity - opacity: 0.0-1.0

Examples

  iex> res = CImg.draw_circle(imge, 100, 80, 40, {0, 0, 255})
Link to this function

draw_circle(cimg, x0, y0, radius, color, opacity, pattern)

View Source

[mut] Draw circle in the image.

Parameters

  • cimg - image object.
  • x0,y0 - circle center location
  • radius - circle radius
  • color - boundary color
  • opacity - opacity: 0.0-1.0
  • pattern - boundary line pattern

Examples

  iex> res = CImg.draw_circle(imge, 100, 80, 40, {0, 0, 255}, 0.3, 0xFFFFFFFF)
Link to this function

draw_graph(cimg, data, color, opacity \\ 1.0, plot_type \\ 1, vertex_type \\ 1, ymin \\ 0.0, ymax \\ 0.0, pattern \\ 4294967295)

View Source

See CImg.NIF.cimg_draw_graph/9.

Link to this function

draw_rect(cimg, x0, y0, x1, y1, color, opacity \\ 1.0, pattern \\ 4294967295)

View Source

[mut] Draw rectangle in the image.

Parameters

  • cimg - image object.
  • x0,y0,x1,y1 - diagonal coordinates. if all of them are integer, they mean actual coodinates. if all of them are float within 0.0-1.0, they mean ratio of the image.
  • color - boundary color
  • opacity - opacity: 0.0-1.0
  • pattern - boundary line pattern: 32bit pattern

Examples

  iex> CImg.draw_rect(img, 50, 30, 100, 80, {255, 0, 0}, 0.3, 0xFF00FF00)
  
  iex> CImg.draw_rect(img, 0.2, 0.3, 0.6, 0.8, {0, 255, 0})

Duplicate the image.

Parameters

  • cimg - image object %CImg{} to duplicate.

Examples

  iex> img = CImg.dup(original)
  # create new image object `img` have same shape and values of original.

[mut] Filling the image with val.

Parameters

  • cimg - image object.
  • val - filling value.

Examples

  iex> res = CImg.fill(img, 0x7f)
Link to this function

get(cimg, x, y \\ 0, z \\ 0, c \\ 0)

View Source

Get the pixel value at (x, y).

Parameters

  • cimg - image object.
  • x,y,z,c - location in the image.

Examples

  iex> x = CImg.get(120, 40)
Link to this function

get_crop(cimg, x0, y0, z0, c0, x1, y1, z1, c1, boundary_conditions \\ 0)

View Source
Link to this function

get_gray(cimg, opt_pn \\ 0)

View Source

Get the gray image of the image.

Parameters

  • cimg - image object %CImg{} to save.
  • opt_pn - intensity inversion: 0 (default) - no-inversion, 1 - inversion

Examples

  iex> gray = CImg.get_gray(img, 1)
  # get inverted gray image
Link to this function

get_resize(cimg, arg, align \\ :none, fill \\ 0)

View Source

Get a new image object resized {x, y}.

Parameters

  • cimg - image object %CImg{} to save.
  • {x, y} - resize width and height
  • align - alignment mode
    • :none - fit resizing
    • :ul - fixed aspect resizing, upper-leftt alignment.
    • :br - fixed aspect resizing, bottom-right alignment.
  • fill - filling value for the margins, when fixed aspect resizing.

Examples

  iex> img = CImg.load("sample.jpg")
  iex> res = CImg.get_resize(img, {300,300}, :ul)

Load a image from file.

Parameters

  • fname - file path of the image. (only jpeg images - xxx.jpg - are available now)

Examples

  iex> img = CImg.load("sample.jpg")

Load a image from memory. You can create an image from loaded binary data of the image file.

Parameters

  • bin - loaded binary of the image file.

Examples

  iex> bin = File.read!("sample.jpg")
  iex> img = CImg.load_from_memory(bin)
Link to this function

map(cimg, lut, boundary \\ 0)

View Source

[mut] mirroring the image on axis

Parameters

  • cimg - image object %CImg{} to save.
  • axis - flipping axis: :x, :y

Examples

  iex> mirror = CImg.mirror(img, :y)
  # vertical flipping

Save the image to the file.

Parameters

  • cimg - image object %CImg{} to save.
  • fname - file path for the image. (only jpeg images - xxx.jpg - are available now)

Examples

  iex> CImg.save(img, "sample.jpg")
Link to this function

set(val, cimg, x, y \\ 0, z \\ 0, c \\ 0)

View Source

[mut] Set the pixel value at (x, y).

Parameters

  • cimg - image object.
  • val - value.
  • x,y,z,c - location in the image.

Examples

  iex> res = CImg.set(0x7f, 120, 40)

Get shape {x,y,z,c} of the image

Parameters

  • cimg - image object.

Examples

  iex> shape = CImg.shape(imge)

Get byte size of the image

Parameters

  • cimg - image object.

Examples

  iex> size = CImg.sizh(imge)
Link to this function

threshold(cimg, val, soft \\ false, strict \\ false)

View Source

[mut] Thresholding the image.

Parameters

  • cimg - image object.
  • val - threshold value
  • soft -
  • strict -

Examples

  iex> res = CImg.threshold(imge, 100)
Link to this function

to_flat(cimg, opts \\ [])

View Source

Get serialized binary of the image from top-left to bottom-right. to_flat/2 helps you to make 32bit-float arrary for the input tensors of DNN model.

Parameters

  • cimg - image object.
  • opts - conversion options
    • { :dtype, xx } - convert pixel value to data type. available: "<f4"/32bit-float, "<u1"/8bit-unsigned-char
    • { :range, {lo, hi} } - normarilzed range when :dtype is "<f4". default range: {0.0, 1.0}
    • :nchw - transform axes NHWC to NCHW.
    • :bgr - convert color RGB -> BGR.

Examples

  iex> img = CImg.load("sample.jpg")
  iex> bin1 = CImg.to_flat(img, [{dtype: "<f4"}, {:range, {-1.0, 1.0}}, :nchw])
  # convert pixel value to 32bit-float in range -1.0..1.0 and transform axis to NCHW.

  iex> bin2 = CImg.to_flat(img, dtype: "<f4")
  # convert pixel value to 32bit-float in range 0.0..1.0.
Link to this function

transfer(cimg, cimg_src, mapping, cx \\ 0, cy \\ 0, cz \\ 0)

View Source

See CImg.NIF.cimg_transfer/6.