View Source CImg (cimg v0.1.21)
A lightweight image processing module in Elixir using CImg, aimed at creating auxiliary routines for Deep Learning.
Session execution
Each function provided by CImg can be used alone (eager execution) or as a set of functions (session execution).
EAGER execution is good for interactive work because you can see the results of your image processing immediately. But it tends to consume more memory than necessary. On the other hand, SESSION execution reduces memory consumption because after assembling the image processing sequence, it is executed all at once.
To perform image processing in SESSION mode, you must assemble a image processing sequence using Elixir's pipe syntax. At the entrance of the pipe, place a function {seed} that generates a %Builder{}, then pipe in the necessary image processing {grow}, and finally place a function {crop} that executes those image processing.
In this document, the following symbols indicate which category each function belongs to.
- {seed} - generate %Builder{}
- {grow} - image processing piece
- {crop} - execute session and get result
Examples
img = CImg.load("sample.jpg")
CImg.builder(img) # generate %Builder{} with %CImg{} as seed image
|> CImg.draw_circle(100, 100, 30, {0,0,255}) # building an image processing session
|> CImg.draw_circle(150, 200, 40, {255,0,0}) # ...
|> CImg.display(disp) # execute above session and display result image on PC screen
Data exchange with Nx
It is easy to exchange %CImg{} 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")
Summary
Functions
{grow} Append image.
{grow} Blending two images.
{grow} Bluring image.
{seed} Returns an empty builder for recording image processing scripts.
{seed} Returns a builder with an existing %CImg{} as the seed image.
{seed} Returns a builder that uses an image read from the file as the seed image.
{seed} Returns a builder whose seed image is an image of shape [x,y,z,c] filled with the value val
.
{seed} Returns a builder that takes as seed image a binary - shape[], dtype - converted to an image
{grow} Booking to clear the image.
{grow} Create color mapped image by lut.
Create image{x,y,z,c} filled val
.
{crop} Display the image on the CImgDisplay object.
{crop} Display the image on the CImgDisplay object.
{crop} Display the image on the Livebook.
{grow} Booking to draw filled circle in the image.
{grow} Booking to draw circle in the image.
{grow} Booking to draw graph.
[grow] Booking to draw line in the image.
[grow] Booking to draw marker.
{grow} Booking to move pixels on the image according to the mapping table.
{grow} Booking to draw rectangle in the image.
{grow} Draw text in th image.
{grow} Booking to fill the image with val
.
{grow} Booking to draw filled circle in the image.
{grow} Booking to draw filled rectangle in the image.
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.
from_binary
helps you to make the image from the serialiezed output tensor of DNN model.
Create the image from %Npy{} format data.
{crop} Get the pixel value at (x, y).
{crop} Extracting a partial image specified in a window from an image.
{grow} Get the gray image of the image.
{grow} 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.
{grow} mirroring the image on axis
{grow} Paint mask image.
{grow} Get a new image object resized {x, y}.
{crop} Returns an image with the script applied to the seed image.
{crop} Returns an image with the script applied to cimg
.
{crop} Save the image to the file.
{grow} Set the pixel value at (x, y).
{crop} Get shape {x,y,z,c} of the image
{crop} Get byte size of the image
{grow} Thresholding the image.
{crop} 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.
{crop} Convert the image to %Npy{} format data.
{grow} transpose the image
Functions
{grow} Append image.
Parameters
- img - %CImg{} or %Builder{}
- img2 - %CImg{}, append image
- axis - append on axis: {:x, :y, :z, :c}
- align -
Examples
img = CImg.load("sample.jpg")
twice = CImg.append(img, img, :x)
{grow} Blending two images.
Parameters
- img - %CImg{} or %Builder{} object.
- mask - %CImg{} object.
- ratio - blending ratio: (1.0-ratio)img + ratiomask
Examples
img = CImg.blend(img_org, img_mask, 0.6)
blur(img, sigma, boundary_conditions \\ true, is_gaussian \\ true)
View Source{grow} Bluring image.
Parameters
- img - %CImg{} or %Builder{}
- sigma -
- boundary_conditions -
- is_gaussian -
Examples
img = CImg.load("sample.jpg")
blured = CImg.blur(img, 0.3)
{seed} Returns an empty builder for recording image processing scripts.
Parameters
None.
Examples
# build a script
script = CImg.builder()
|> CImg.gray()
|> CImg.resize({256, 256})
# apply the script to an image.
seed = CImg.load("sample.jpg")
result = CImg.run(script, seed)
{seed} Returns a builder with an existing %CImg{} as the seed image.
Parameters
- img - %CImg{}
Examples
cimg = CImg.load("sample.jpg")
result = CImg.builder(cimg) # create %Builder{} has cimg
|> CImg.draw_circle(100, 100, 30, {0, 255, 0})
|> CImg.run()
{seed} Returns a builder that uses an image read from the file as the seed image.
Parameters
- atom - image file format:
:jpeg
or:png
- fname - file name
Examples
result = CImg.builder(:jpeg, "sample.jpg")
|> CImg.draw_circle(100, 100, 30, {0, 255, 0})
|> CImg.run()
{seed} Returns a builder whose seed image is an image of shape [x,y,z,c] filled with the value val
.
Parameters
- x,y,z,c - shape of image
- val - filling value
Examples
res = CImg.builder(640, 480, 1, 3, 64)
|> CImg.draw_circle(100, 100, 30, {0, 255, 0})
|> CImg.run()
{seed} Returns a builder that takes as seed image a binary - shape[], dtype - converted to an image
Parameters
- bin - binary
- x,y,z,c - shape of the image represented by
bin
- opts - convertion options
- { :dtype, xxx } - convert data type to pixel. available: "<f4"/32-bit-float, "<u1"/8bit-unsigned-char
- { :range, {lo, hi} } - convert range lo..hi to 0..255. default range: {0.0, 1.0}
- { :gauss, {{mu-R,sigma-R},{mu-G,sigma-G},{mu-B,sigma-B}} } - inverse normalization by Gaussian distribution.
- :nchw - transform axes NCHW to NHWC.
- :bgt - convert color BGR -> RGB.
Examples
result = CImg.builder(bin 640, 480, 1, 3, dtype: "<f4")
|> CImg.draw_circle(100, 100, 30, {0, 255, 0})
|> CImg.run()
{grow} Booking to clear the image.
Parameters
- builder - %Builder{}.
Examples
result = CImg.builder(:file, "sample.jpg")
|> CImg.clear()
|> CImg.run()
{grow} Create color mapped image by lut.
Parameters
- img - %CImg{} or %Builder{}
- 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)
{crop} Display the image on the CImgDisplay object.
Parameters
- img - %CImg{} or %Builder{}
- display - CImgDisplay object
Examples
CImg.display(cimg)
CImg.builder(cimg)
|> CImg.draw_circle(100, 100, 50, {255, 0, 0})
|> CImg.display()
{crop} Display the image on the CImgDisplay object.
Parameters
- cimg - %CImg{} or %Builder{}
- display - CImgDisplay object
Examples
disp = CImgDisplay.create(img, "Sample")
CImg.display(img, disp)
{crop} Display the image on the Livebook.
Parameters
- img - %CImg{} or %Builder{}
- mime_type - image file format:
:jpeg
,:png
Examples
CImg.builder(:file, "sample.jpg")
|> CImg.display_kino(:jpeg)
{grow} Booking to draw filled circle in the image.
Parameters
- builder - %Builder{}
- x0,y0 - circle center location
- radius - circle radius
- color - filling color
- opacity - opacity: 0.0-1.0
Examples
result = CImg.builder(cimg)
|> CImg.draw_circle(imge, 100, 80, 40, {0, 0, 255})
|> CImg.run()
{grow} Booking to draw circle in the image.
Parameters
- builder - %Builder{}
- x0,y0 - circle center location
- radius - circle radius
- color - boundary color
- opacity - opacity: 0.0-1.0
- pattern - boundary line pattern
Examples
result = CImg.builder(cimg)
|> CImg.draw_circle(imge, 100, 80, 40, {0, 0, 255}, 0.3, 0xFFFFFFFF)
|> CImg.run()
draw_graph(builder, data, color, opacity \\ 1.0, plot_type \\ 1, vertex_type \\ 1, ymin \\ 0.0, ymax \\ 0.0, pattern \\ 4_294_967_295)
View Source{grow} Booking to draw graph.
Parameters
- builder - %Builder{}
- data - plot data (%CImg{})
- color - RGB color tuple: {R,G,B} where 0 竕ヲ R,G,B 竕ヲ 255
- opacity -
- plot_type -
- 0 = No plot.
- 1 = Plot using segments.
- 2 = Plot using cubic splines.
- 3 = Plot with bars.
- vertex_type -
- 0 = No points.
- 1 = Point.
- 2 = Straight cross.
- 3 = Diagonal cross.
- 4 = Filled circle.
- 5 = Outlined circle.
- 6 = Square.
- 7 = Diamond.
- ymin, ymax - lower and upper bound of the y-range
- pattern - line style
Examples
CImg.builder(screen)
|> CImg.draw_graph(CImg.get_crop(image, 0, y, 0, 0, width-1, y, 0, 0), red, 1.0, 1, 0, 255.0, 0.0)
|> CImg.draw_graph(CImg.get_crop(image, 0, y, 0, 1, width-1, y, 0, 1), green, 1.0, 1, 0, 255.0, 0.0)
|> CImg.draw_graph(CImg.get_crop(image, 0, y, 0, 2, width-1, y, 0, 2), blue, 1.0, 1, 0, 255.0, 0.0)
|> CImg.display(draw_disp)
[grow] Booking to draw line in the image.
Parameters
- builder - %Builder{}
- x1,y1,x2,y2 - ends of the line. if all of them are integer, they mean actual coodinates. if all of them are float, they mean ratio of the image.
- color - line color
- opts
- thick: val - thick of line
- opacity: val - opacity: 0.0-1.0
- pattern: val - boundary line pattern: 32bit pattern
Examples
CImg.builder(img)
|> CImg.draw_line(10, 10, 20, 30, :white, thick: 3)
[grow] Booking to draw marker.
Parameters
- builder - %Builder{}
- x,y - location. if all of them are integer, they mean actual coodinates. if all of them are float, they mean ratio of the image.
- color - marker color
- opts
- size - size of marker (>= 0)
- mark - shape of marker (only :circle is avalable now)
{grow} Booking to move pixels on the image according to the mapping table.
Parameters
- img - %CImg{} or %Builder{}
- 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]}]
result = CImg.builder(:jpeg, "sample.jpg")
|> CImg.draw_morph(map)
|> CImg.run()
draw_rect(builder, x0, y0, x1, y1, color, opacity \\ 1.0, pattern \\ 4_294_967_295)
View Source{grow} Booking to draw rectangle in the image.
Parameters
- builder - %Builder{}
- 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.builder(cimg)
|> CImg.draw_rect(img, 50, 30, 100, 80, {255, 0, 0}, 0.3, 0xFF00FF00)
|> CImg.display()
CImg.builder(cimg)
|> CImg.draw_rect(img, 0.2, 0.3, 0.6, 0.8, {0, 255, 0})
|> CImg.display()
draw_text(builder, x, y, text, font_height, fg_color, bg_color \\ :transparent, opacity \\ 1.0)
View Source{grow} Draw text in th image.
Parameters
- builder - %Builder{}
- x,y - position on the image where the text will begin to be drawn.
- text - the text to be drawn.
- font_height - font height in pixels.
- fg_color - foreground color. choose one of the following:
:white,:sliver,:gray,:black,:red,:maroon,:yellow,:olive, :lime,:green,:aqua,:teal,:blue,:navy,:fuchsia,:purple, :transparent
- bg_color - background color.
- opacity - opacity: 0.0..1.0.
Examples
result = CImg.draw_text(builder, 10, 20, "Hello world!", 32, :white)
{grow} Booking to fill the image with val
.
Parameters
- builder - %Builder{}
- val - filling value.
Examples
result = CImg.builder(cimg)
|> CImg.fill(img, 0x7f)
|> CImg.run()
fill_circle(builder, x0, y0, radius, color, opacity \\ 1.0, pattern \\ 4_294_967_295)
View Source{grow} Booking to draw filled circle in the image.
Parameters
- builder - %Builder{}
- x0,y0 - circle center location
- radius - circle radius
- color - filling color
- opacity - opacity: 0.0-1.0
- pattern - boundary line pattern
Examples
result = CImg.builder(cimg)
|> CImg.fill_circle(imge, 100, 80, 40, {0, 0, 255}, 0xF0F0F0F0)
|> CImg.run()
fill_rect(builder, x0, y0, x1, y1, color, opacity \\ 1.0, pattern \\ 4_294_967_295)
View Source{grow} Booking to draw filled rectangle in the image.
Parameters
- builder - %Builder{}
- 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
Examples
CImg.builder(cimg)
|> CImg.fill_rect(img, 50, 30, 100, 80, {255, 0, 0}, 0.3)
|> CImg.display()
CImg.builder(cimg)
|> CImg.fill_rect(img, 0.2, 0.3, 0.6, 0.8, {0, 255, 0})
|> CImg.display()
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
bin = File.read!("sample.jpg")
jpeg = CImg.from_binary(bin)
Create image{x,y,z,c} from raw binary.
from_binary
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.
- opts - convertion options
- { :dtype, xxx } - convert data type to pixel. available: "<f4"/32-bit-float, "<u1"/8bit-unsigned-char
- { :range, {lo, hi} } - convert range lo..hi to 0..255. default range: {0.0, 1.0}
- { :gauss, {{mu-R,sigma-R},{mu-G,sigma-G},{mu-B,sigma-B}} } - inverse normalization by Gaussian distribution.
- :nchw - transform axes NCHW to NHWC.
- :bgt - convert color BGR -> RGB.
Examples
bin = TflInterp.get_output_tensor(__MODULE__, 0)
img = CImg.from_binary(bin, 300, 300, 1, 3, dtype: "<f4")
img = CImg.from_binary(bin, 300, 300, 1, 3, gauss: {{103.53,57.375},{116.28,57.12},{123.675,58.395}})
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)
{crop} Get the pixel value at (x, y).
Parameters
- img - %CImg{} or %Builder{}
- x,y,z,c - location in the image.
Examples
val = CImg.get(img, 120, 40)
get_crop(img, x0, y0, z0, c0, x1, y1, z1, c1, boundary_conditions \\ 0)
View Source{crop} Extracting a partial image specified in a window from an image.
Parameters
- img - %CImg{} or %Builder{}
- x0,y0,z0,c0, x1,y1,z1,c1 - window
- bundary_condition -
Examples
partial = CImg.get_crop(img, 100, 100, 0, 0, 400, 600, 0, 3)
{grow} Get the gray image of the image.
Parameters
- img - %CImg{} or %Builder{}
- opt_pn - intensity inversion: 0 (default) - no-inversion, 1 - inversion
Examples
gray = CImg.gray(img)
{grow} 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")
{grow} mirroring the image on axis
Parameters
- img - %CImg{} or %Builder{}
- axis - flipping axis: :x, :y
Examples
mirror = CImg.mirror(img, :y)
# vertical flipping
{grow} Paint mask image.
Parameters
- img - %CImg{} or %Builder{} object.
- mask - %CImg{} object, binary image.
- lut - color map.
- opacity - opacity: (1.0-opacity)img + opacitymask
Examples
img = CImg.paint_mask(img_org, img_mask, [{255,0,0}], 0.6)
{grow} Get a new image object resized {x, y}.
Parameters
- cimg - image object.
- {x, y} - resize width and height or scale - resize scale cimg - get the size from the cimg object
- align - alignment mode
- :none - fit resizing
- :ul - fixed aspect resizing, upper-leftt alignment.
- :br - fixed aspect resizing, bottom-right alignment.
- :crop - resizing the center crop to {x, y}.
- fill - filling value for the margins, when fixed aspect resizing.
Examples
img = CImg.load("sample.jpg")
result = CImg.get_resize(img, {300,300}, :ul)
{crop} Returns an image with the script applied to the seed image.
Parameters
- builder - %Builder{}
Examples
result = CImg.builder(100, 100, 1, 3, 0)
|> CImg.draw_circle(100, 100, 30, {0, 255, 0})
|> CImg.run()
{crop} Returns an image with the script applied to cimg
.
Parameters
- builder - %Builder{}
- cimg - %CImg{}
Examples
cimg = CImg.load("sample.jpg")
result = CImg.builder()
|> CImg.draw_circle(100, 100, 30, {0, 255, 0})
|> CImg.runit(cimg)
{crop} Save the image to the file.
Parameters
- img - %CImg{} or %Builder{}
- fname - file path for the image. (only jpeg images - xxx.jpg - are available now)
Examples
CImg.save(img, "sample.jpg")
{grow} Set the pixel value at (x, y).
Parameters
- builder - %Builder{}
- val - value.
- x,y,z,c - location in the image.
Examples
result = CImg.builder(cimg)
|> CImg.set(0x7f, 120, 40)
|> CImg.run()
{crop} Get shape {x,y,z,c} of the image
Parameters
- img - %CImg{} or %Builder{}
Examples
shape = CImg.shape(img)
{crop} Get byte size of the image
Parameters
- img - %CImg{} or %Builder{}
Examples
size = CImg.size(img)
{grow} Thresholding the image.
Parameters
- img - %CImg{} or %Builder{} object.
- val - threshold value
- soft -
- strict -
Examples
res = CImg.threshold(img, 100)
{crop} 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
img - %CImg{} or %Builder{}
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} } - range transformation when :dtype is "<f4". default range: {0.0, 1.0}
- { :gauss, {{mu-R,sigma-R},{mu-G,sigma-G},{mu-B,sigma-B}} } - normalize by Gaussian distribution.
- :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.
bin3 = CImg.to_binary(img, gauss: {{103.53,57.375},{116.28,57.12},{123.675,58.395}})
# convert pixel value to 32bit-float normalized by Gaussian destribution: mu-R=103.53, sigma-R=57.375,...
{crop} Convert the image to %Npy{} format data.
Parameters
- img - %CImg{} or %Builder{}
- opts - conversion options
- { :dtype, xx } - convert pixel value to data type. available: "<f4"/32bit-float, "<u1"/8bit-unsigned-char
- { :range, {lo, hi} } - range transformation when :dtype is "<f4". default range: {0.0, 1.0}
- { :gauss, {{mu-R,sigma-R},{mu-G,sigma-G},{mu-B,sigma-B}} } - normalize by Gaussian distribution.
- :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.
{grow} transpose the image
Parameters
- img - %CImg{} or %Builder{}
Examples
transposed = CImg.transpose(img)