CImg (cimg v0.1.8) 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 most important point. Some of the functions in this module mutably rewrite the original image, when they recieve the image as %Builder{}.

  img = CImg.load("sample.jpg")   # create %CImg{}
  CImg.builder(img)               # duplicate img and create %Builder{} with it
  |> CImg.fill(0)                              # rewrite
  |> CImg.draw_circle(100, 100, 30, {0,0,255}) # rewrite
  |> CImg.display(disp)

Platform

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

  • Windows MSYS2/MinGW64
  • WSL2/Ubuntu 20.04

Data exchange with Nx

It is easy to exchange CImg images and Nx tensors.

# convert CImg image to Nx.Tensor
iex> img0 = CImg.load("sample.jpg")
%CImg{{2448, 3264, 1, 3}, handle: #Reference<0.2112145695.4205182979.233827>}
iex> tensor = CImg.to_binary(img0, dtype: "<u8")
       |> Nx.from_binary({:u, 8})

# convert Nx.Tensor to CImg image
iex> img1 = Nx.to_binary(tensor)
       |>CImg.from_bin(2448, 3264, 1, 3, "<u8")

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

Create color mapped image by lut.

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.

Create a image from jpeg/png format binary. You can create an image from loaded binary of the JPEG/PNG file.

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.

Create the image from %Npy{} format data.

Get the pixel value at (x, y).

Get the gray image of the image.

Get the inverted image of the image.

Load a image from file. The file types supported by this function are jpeg, ping and bmp. The file extension identifies which file type it is.

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

mirroring the image on axis

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

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_binary/2 helps you to make 32bit-float arrary for the input tensors of DNN model or jpeg/png format binary on memory.

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.

to_jpeg(cimg) deprecated

Convert the image to JPEG binary.

Convert the image to %Npy{} format data.

to_png(cimg) deprecated

Convert the image to PNG binary.

Pick the pixels on the source image and write on the distination image according to the mapping table.

Link to this section Functions

Link to this function

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

View Source

Bluring image.

Parameters

  • img - %CImg{} or %Builder{} object
  • sigma -
  • boundary_conditions -
  • is_gaussian -

Examples

  img = CImg.load("sample.jpg")
  blured = CImg.blur(img, 0.3)

See CImg.Builder.builder/1.

Link to this function

builder(x, y, z, c, val)

View Source

See CImg.Builder.builder/5.

Link to this function

color_mapping(cimg, lut \\ :default, boundary \\ 0)

View Source

Create color mapped image by lut.

Parameters

  • cimg - image object %CImg{} to save.
  • lut - color map. build-in or user defined.
    • build-in map: {:default, :lines, :hot, :cool, :jet}
    • user defined: list of color tupple, [{0,0,0},{10,8,9},{22,15,24}...].
  • boundary - handling the pixel value outside the color map range.
    • 0 - set to zero value.
    • 1 -
    • 2 - repeat from the beginning of the color map.
    • 3 - repeat while wrapping the color map.

Examples

  gray = CImg.load("sample.jpg") |> CImg.gray()
  
  jet = CImg.color_mapping(gray, :jet)
  # heat-map coloring.

  custom = CImg.color_mapping(gray, [{0,0,0},{10,8,9},{22,15,24}], 2)
  # custom coloring.

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

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

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

View Source
This function is deprecated. Use `from_binary/6` instead.

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

  bin = TflInterp.get_output_tensor(__MODULE__, 0)
  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

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

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

View Source

[mut] Draw filled circle in the image.

Parameters

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

Examples

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

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

View Source

[mut] Draw circle in the image.

Parameters

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

Examples

  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 \\ 4_294_967_295 )

View Source

[mut] Draw graph.

Parameters

  • cimg - image object %CImg{} to save.
Link to this function

draw_rect(builder, x0, y0, x1, y1, color, opacity \\ 1.0, pattern \\ 4_294_967_295)

View Source

[mut] Draw rectangle in the image.

Parameters

  • builder - builder 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

  CImg.draw_rect(img, 50, 30, 100, 80, {255, 0, 0}, 0.3, 0xFF00FF00)

  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

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

[mut] Filling the image with val.

Parameters

  • builder - builder object.
  • val - filling value.

Examples

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

from_binary(jpeg_or_png)

View Source

Create a image from jpeg/png format binary. You can create an image from loaded binary of the JPEG/PNG file.

Parameters

  • jpeg_or_png - loaded binary of the image file.

Examples

  jpeg = File.read!("sample.jpg")
  img = CImg.from_binary(jpeg)
Link to this function

from_binary(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

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

Create the image from %Npy{} format data.

Parameters

  • npy - %Npy{} has 3 rank.

Examples

  {:ok, npy} = Npy.load("image.npy")
  img = CImg.from_npy(npy)
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

  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

Get crop.

Parameters

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

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

  gray = CImg.gray(img, 1)
  # get inverted gray image

Get the inverted image of the image.

Examples

  inv = CImg.invert(img)
  # get inverted image

Load a image from file. The file types supported by this function are jpeg, ping and bmp. The file extension identifies which file type it is.

Parameters

  • fname - file path of the image.

Examples

  img = CImg.load("sample.jpg")
This function is deprecated. Use `from_binary/1` instead.

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

  bin = File.read!("sample.jpg")
  img = CImg.load_from_memory(bin)

mirroring the image on axis

Parameters

  • cimg - %CImg{} or %Builder{} object.
  • axis - flipping axis: :x, :y

Examples

  mirror = CImg.mirror(img, :y)
  # vertical flipping
Link to this function

resize(img, size, align \\ :none, fill \\ 0)

View Source

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

Parameters

  • cimg - image object.
  • {x, y} - resize width and height or scale - resize scale
  • 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

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

See CImg.Builder.runit/1.

Save the image to the file.

Parameters

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

Examples

  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

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

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

Parameters

  • cimg - image object.

Examples

  shape = CImg.shape(imge)

Get byte size of the image

Parameters

  • builder - builder object.

Examples

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

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

View Source

Thresholding the image.

Parameters

  • img - %CImg{} or %Builder{} object.
  • val - threshold value
  • soft -
  • strict -

Examples

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

to_binary(cimg, opts \\ [])

View Source

Get serialized binary of the image from top-left to bottom-right. to_binary/2 helps you to make 32bit-float arrary for the input tensors of DNN model or jpeg/png format binary on memory.

Parameters

  • cimg - image object.

  • opts - conversion options

    • :jpeg - convert to JPEG format binary.
    • :png - convert to PNG format binary.

    following options can be applied when converting the image to row binary.

    • { :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

  img = CImg.load("sample.jpg")
  
  jpeg = CImg.to_binary(img, :jpeg)
  # convert to JPEG format binary on memory.
  
  png = CImg.to_binary(img, :png)
  # convert to PNG format binary on memory.
  
  bin1 = CImg.to_binary(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.

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

to_flat(cimg, opts \\ [])

View Source
This function is deprecated. Use `to_binary/2` instead.

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

  img = CImg.load("sample.jpg")
  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.

  bin2 = CImg.to_flat(img, dtype: "<f4")
  # convert pixel value to 32bit-float in range 0.0..1.0.
This function is deprecated. Use `to_binary/2` instead.

Convert the image to JPEG binary.

Parameters

  • cimg - image object.

Examples

  jpeg = CImg.load("sample.jpg")
    |> CImg.resize({512, 512})
    |> CImg.to_jpeg()
  Kino.Image.new(jpeg, "image/jpeg")
Link to this function

to_npy(cimg, opts \\ [])

View Source

Convert the image to %Npy{} format data.

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

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

  npy1 =
    img
    |> CImg.to_npy()

  npy2 =
    img
    |> CImg.to_npy([{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.
This function is deprecated. Use `to_binary/2` instead.

Convert the image to PNG binary.

Parameters

  • cimg - image object.

Examples

  png = CImg.load("sample.jpg")
    |> CImg.to_png()
Link to this function

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

View Source

Pick the pixels on the source image and write on the distination image according to the mapping table.

Parameters

  • cimg - distination image object.
  • cimg_src - source image.
  • mapping - mapping table. ex) [{[10,10],[10,20]}], move pixel at [10,10] to [10,20]
  • cx, cy, cz - location of upper-left mapping table on both images.

Examples

  map = [{[20,20],[25,25]}, {[20,21],[25,26]}]
  src = CImg.load("sample.jpg")
  dst = CImg.builder(src)
    |> CImg.transfer(src, map)
    |> CImg.runit()