CImg (cimg v0.1.6) 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_flat(img0, dtype: "<u8").data
|> Nx.from_binary({:u, 8})
# convert Nx.Tensor to CImg image
iex> img1 = Nx.to_binary(tensor)
|>CImg.create_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 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.
[mut] Draw circle in the image.
[mut] Draw graph.
[mut] Draw rectangle in the image.
Duplicate the image.
[mut] Filling the image with val
.
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.
Create color mapped image by lut.
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
[mut] Thresholding 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.
Convert the image to JPEG binary.
Convert the image to %Npy{} format data.
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
blur(img, sigma, boundary_conditions \\ true, is_gaussian \\ true)
View SourceBluring image.
Parameters
- img - %CImg{} or %Builder{} object
- sigma -
- boundary_conditions -
- is_gaussian -
Examples
img = CImg.load("sample.jpg")
blured = CImg.blur(img, 0.3)
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)
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)
[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})
[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)
draw_graph(cimg, data, color, opacity \\ 1.0, plot_type \\ 1, vertex_type \\ 1, ymin \\ 0.0, ymax \\ 0.0, pattern \\ 4294967295)
View Source[mut] Draw graph.
Parameters
- cimg - image object %CImg{} to save.
draw_rect(builder, x0, y0, x1, y1, color, opacity \\ 1.0, pattern \\ 4294967295)
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)
Create the image from %Npy{} format data.
Parameters
- npy - %Npy{} has 4 rank.
Examples
{:ok, npy} = Npy.load("image.npy")
img = CImg.from_npy(npy)
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)
get_crop(cimg, x0, y0, z0, c0, x1, y1, z1, c1, boundary_conditions \\ 0)
View SourceGet 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")
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)
Create color mapped image by lut.
Parameters
- cimg - image object %CImg{} to save.
- lut - color mapping lut name - {"default", "lines", "hot", "cool", "jet"}
- boundary -
mirroring the image on axis
Parameters
- cimg - %CImg{} or %Builder{} object.
- axis - flipping axis: :x, :y
Examples
mirror = CImg.mirror(img, :y)
# vertical flipping
Get a new image object resized {x, y}.
Parameters
- cimg - image object.
- {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
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")
[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)
[mut] Thresholding the image.
Parameters
- img - %CImg{} or %Builder{} object.
- val - threshold value
- soft -
- strict -
Examples
res = CImg.threshold(imge, 100)
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.
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")
Convert the image to %Npy{} format data.
Parameters
- cimg - image object.
Examples
npy = CImg.load("sample.jpg")
|> CImg.to_npy()
Convert the image to PNG binary.
Parameters
- cimg - image object.
Examples
png = CImg.load("sample.jpg")
|> CImg.to_png()
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()