Liking cljdoc? Tell your friends :D

clojure2d.pixels

Operations on pixel levels.

Content

Namespace defines three main concepts:

  • Pixels - channel values packed into array.
  • Processors - parallel Pixels processing functions (like filters).
  • Bins - log density renderer

Pixels

Pixels is type which represents image as int array divided into color channels. Layout is linear and interleaved which means that array is 1D and each pixel is represented by four consecutive values R, G, B, A. After first row goes second and so on.

Pixels allows mutation, you can read and set channel value or color:

  • get-value, [[set-value]] - read or set channel value for given pixel and channel. Value should be within [0-255] range.
  • get-color, [[set-color]] - read or set color for given pixel. Returned color has [[Vec4]] type.
  • get-channel, [[set-channel]] - read or set whole channel as ints.

Pixel access can be made by (x,y) coordinates or by index which is equivalent to (+ x (* y width)).

Pixels implement [[ImageProto]].

Creation / conversions

To create empty Pixels, call pixels.

You can also get and set Pixels from and to Images and Canvases or read from file.

Processors

Library supports several processing functions and helpers to parallely manipulate channels or colors. All functions are not destrictive, that means new object is created to store result of manipulation. Every processor accept one or more filtering functions which do the job. There are three main functions:

  • filter-colors - to process colors. Uses function f which accepts color and should return color. Can be used to convert Pixels between different color spaces.
  • filter-channels - to process channel values. Uses function f which accepts channel number (values from 0 to 3), target Pixels and source Pixels and returns integer. You can provide different function for every channel. Can be used to apply filter (like blur).
  • blend-channels - to process pair of Pixels. Uses function f which accepts channel number, target and two Pixel values. compose-channels wrapper can be used to compose two Pixels using one of the blending functions defined in [[clojure2d.colors]] namespace.

Additionally other processing functions are prepared in case you want write own filters or converters:

Color space

To convert whole Pixels into different color space use filter-colors and pass one of the color space conversion functions defined under [[colorspaces*]]. Always use normalized version.

(filter-colors c/to-HSB* pixels-object)

Filters

There are several ready to use filters. All defined under [[filters-list]] variable. Some of the filters are creators and should be called with parametrization.

(filter-channels gaussian-blur-3 pixels-object)
(filter-channels (posterize 10) pixels-object)

Composing

To compose two Pixels use compose-channels and use name of composing function defined [[blends-list]]. Instead of name you can pass custom composing function.

(compose-channels :multiply pixels-1 pixels-2)

Log Density Rendering

Log Density Renderer was orginally created for fractal flames rendering and produces very smooth results. Details are described in this paper.

Renderer is point based (no other primitives) and supports selection of antialiasing (reconstruction) filters. Density estimation is not supported.

Rendering algorithm collects color channels values and counts number of hits for each pixel. For each pixel weighted average of all color values is calculated and log of number of hits gives alpha value. Pixel color is blended with background using alpha.

Rendering

First you have to create renderer with renderer function. By default no filter is used. In case you want to use filter call with: filter name as keyword (see below), optional: filter radius (default 2.0) and other filter parameters.

To set point call [[set-color]].

Antialiasing filters

Below you have list of all available antialiasing filters. Each filter has radius and spread parameter.

  • :gaussian
  • :box - only radius
  • :sinc - Windowed sinc filter
  • :mitchell - Mitchell-Netravali filter, additional parameters: B and C (default: 1/3)
  • :cubic
  • :catmull
  • :triangle
  • :cosinebell
  • :blackmann-harris
  • :hann
  • :none or nil - no filter

Converting

To convert renderer to Pixels just call to-pixels method with optional configuration. Configuration gives you possibility to control process of transformation to RGB data.

Configuration is a map with following fields:

  • :background - color of the background (default: :black)
  • :gamma-alpha - gamma correction for alpha
  • :gamma-color - gamma correction for color, to adjust vibrancy
  • :vibrancy: 0.0 - use calculated color 1.0 - use gamma corrected color (0.0-1.0) - mix between above
  • :saturation - adjust saturation (0-2)
  • :brightness - adjust brightness (0-2)
  • :contrast - adjust contrast (0-2)

Parallel rendering

Construction of renderer enables parallel computing. Just create as many renderers as you want (you may use [[available-tasks]] value), run rendering in separate threads and then merge result with merge-renderers.

Operations on pixel levels.

## Content

Namespace defines three main concepts:

* Pixels - channel values packed into array.
* Processors - parallel Pixels processing functions (like filters).
* Bins - log density renderer

## Pixels

Pixels is type which represents image as int array divided into color channels. Layout is linear and interleaved which means that array is 1D and each pixel is represented by four consecutive values R, G, B, A. After first row goes second and so on.

Pixels allows mutation, you can read and set channel value or color:

* [[get-value]], [[set-value]] - read or set channel value for given pixel and channel. Value should be within `[0-255]` range.
* [[get-color]], [[set-color]] - read or set color for given pixel. Returned color has [[Vec4]] type.
* [[get-channel]], [[set-channel]] - read or set whole channel as `ints`.

Pixel access can be made by `(x,y)` coordinates or by index which is equivalent to `(+ x (* y width))`.

Pixels implement [[ImageProto]].

### Creation / conversions

To create empty Pixels, call [[pixels]].

You can also get and set Pixels from and to Images and Canvases or read from file.

## Processors

Library supports several processing functions and helpers to parallely manipulate channels or colors. All functions are not destrictive, that means new object is created to store result of manipulation. Every processor accept one or more filtering functions which do the job.
There are three main functions:

* [[filter-colors]] - to process colors. Uses function `f` which accepts color and should return color. Can be used to convert Pixels between different color spaces.
* [[filter-channels]] - to process channel values. Uses function `f` which accepts channel number (values from 0 to 3), target Pixels and source Pixels and returns integer. You can provide different function for every channel. Can be used to apply filter (like blur).
* [[blend-channels]] - to process pair of Pixels. Uses function `f` which accepts channel number, target and two Pixel values. [[compose-channels]] wrapper can be used to compose two Pixels using one of the blending functions defined in [[clojure2d.colors]] namespace.

Additionally other processing functions are prepared in case you want write own filters or converters:

* [[filter-colors-xy]] - process colors using function `f` which accepts Pixels and current position.
* [[filter-channel]] - iterate through channel, `f` accepts channel value and returns new channel value
* [[filter-channel-xy]] - iterate through channel, `f` accepts channel, Pixels and x,y position
* [[blend-channels]] and [[blend-channel-xy]] - similar to two above, `f` accepts two Pixels instead of one.

### Color space

To convert whole Pixels into different color space use [[filter-colors]] and pass one of the color space conversion functions defined under [[colorspaces*]]. Always use normalized version.

```
(filter-colors c/to-HSB* pixels-object)
```

### Filters

There are several ready to use filters. All defined under [[filters-list]] variable. Some of the filters are creators and should be called with parametrization.

```
(filter-channels gaussian-blur-3 pixels-object)
(filter-channels (posterize 10) pixels-object)
```

### Composing

To compose two Pixels use [[compose-channels]] and use name of composing function defined [[blends-list]]. Instead of name you can pass custom composing function.

```
(compose-channels :multiply pixels-1 pixels-2)
```

## Log Density Rendering

Log Density Renderer was orginally created for fractal flames rendering and produces very smooth results. Details are described in this [paper](http://flam3.com/flame.pdf).

Renderer is point based (no other primitives) and supports selection of antialiasing (reconstruction) filters. Density estimation is not supported.

Rendering algorithm collects color channels values and counts number of hits for each pixel. For each pixel weighted average of all color values is calculated and log of number of hits gives alpha value. Pixel color is blended with background using alpha.

### Rendering

First you have to create renderer with [[renderer]] function. By default no filter is used. 
In case you want to use filter call with: filter name as keyword (see below), optional: filter radius (default 2.0) and other filter parameters.

To set point call [[set-color]].

#### Antialiasing filters

Below you have list of all available antialiasing filters. Each filter has radius and spread parameter.

* :gaussian
* :box - only radius
* :sinc - Windowed sinc filter
* :mitchell - Mitchell-Netravali filter, additional parameters: B and C (default: 1/3)
* :cubic
* :catmull
* :triangle
* :cosinebell
* :blackmann-harris
* :hann
* :none or `nil` - no filter

### Converting

To convert renderer to Pixels just call [[to-pixels]] method with optional configuration. Configuration gives you possibility to control process of transformation to RGB data.

Configuration is a map with following fields:

* :background - color of the background (default: :black)
* :gamma-alpha - gamma correction for alpha
* :gamma-color - gamma correction for color, to adjust vibrancy
* :vibrancy:
    0.0 - use calculated color
    1.0 - use gamma corrected color
    (0.0-1.0) - mix between above
* :saturation - adjust saturation (0-2)
* :brightness - adjust brightness (0-2)
* :contrast - adjust contrast (0-2)

### Parallel rendering

Construction of renderer enables parallel computing. Just create as many renderers as you want (you may use [[available-tasks]] value), run rendering in separate threads and then merge result with [[merge-renderers]].
raw docstring

*pixels-edge*clj

If you access pixels which is outside possible range. You'll always get some value. You can control what is returned by setting this variable. Possible values are:

  • :zero - set 0
  • :edge - value from the edge of the image (left, right, top, bottom or corners) (default)
  • :wrap - wrap around image
  • or channel value 0-255 - set specific value
If you access pixels which is outside possible range. You'll always get some value. You can control what is returned by setting this variable. Possible values are:

* `:zero` - set `0` 
* `:edge` - value from the edge of the image (left, right, top, bottom or corners) (default)
* `:wrap` - wrap around image
* or channel value 0-255 - set specific value
sourceraw docstring

add-pixel!clj

(add-pixel! r x y)
(add-pixel! r x y c)

Add pixel to renderer buffer.

Add pixel to renderer buffer.
sourceraw docstring

blend-channelclj

(blend-channel f)
(blend-channel f ch target p1 p2)

Blend one channel, write result into target.

Blending function should two channel values and return new channel value.

This should be considered as helper function for blend-channels.

Blend one channel, write result into target.

Blending function should two channel values and return new channel value.

This should be considered as helper function for [[blend-channels]].
sourceraw docstring

blend-channel-xyclj

(blend-channel-xy f)
(blend-channel-xy f ch target p1 p2)

Blend one channel, write result into target.

Blending function should accept channel, two Pixels and position x,y.

Blend one channel, write result into target.

Blending function should accept channel, two `Pixels` and position x,y.
sourceraw docstring

blend-channelsclj

(blend-channels f p1 p2)
(blend-channels f do-alpha? p1 p2)
(blend-channels f0 f1 f2 f3 p1 p2)

Blend channels parallelly.

Similar to filter-channels. Bleding function should accept: channel, target and two source pixels.

Blend channels parallelly.

Similar to `filter-channels`. Bleding function should accept: channel, target and two source pixels.
sourceraw docstring

box-blurclj

(box-blur radius)

Create box blur for given radius.

Create box blur for given radius.
sourceraw docstring

box-blur-1clj

source

box-blur-2clj

source

box-blur-3clj

source

box-blur-5clj

source

brightness-contrastclj

(brightness-contrast brightness)
(brightness-contrast brightness contrast)

Create brightness / contrast filter.

Values from [0-2].

Create brightness / contrast filter.

Values from [0-2].
sourceraw docstring

clone-pixelsclj

(clone-pixels p)

Clone Pixels, returns new object

Clone Pixels, returns new object
sourceraw docstring

compose-channelsclj

(compose-channels n p1 p2)
(compose-channels n do-alpha? p1 p2)
(compose-channels n1 n2 n3 p1 p2)
(compose-channels n1 n2 n3 n4 p1 p2)

Compose channels with blending functions.

You can give blending method name as keyword defined in [[blends-names]]. Or it can be blending function which accepts 2 doubles from 0.0 to 1.0 and returns double (0.0 - 1.0).

When there is no processing function for alpha, W3C alpha blending is applied.

Compose channels with blending functions.

You can give blending method name as keyword defined in [[blends-names]]. Or it can be blending function which accepts 2 doubles from 0.0 to 1.0 and returns double (0.0 - 1.0).

When there is no processing function for alpha, W3C alpha blending is applied.
sourceraw docstring

compositeclj

(composite n)

Create java.awt.Composite object which can be used in [[set-composite]].

Used to change default blending during drawing.

Create java.awt.Composite object which can be used in [[set-composite]].

Used to change default blending during drawing.
sourceraw docstring

dilateclj

Dilate filter. See: dilate-cross.

Dilate filter. See: [[dilate-cross]].
sourceraw docstring

dilate-crossclj

Dilate using 5 pixels. See: dilate.

Dilate using 5 pixels. See: [[dilate]].
sourceraw docstring

equalizeclj

(equalize ch target p)

Equalize histogram.

Equalize histogram.
sourceraw docstring

erodeclj

Erode filter. See: erode-cross.

Erode filter. See: [[erode-cross]].
sourceraw docstring

erode-crossclj

Erode using 5 pixels. See: erode.

Erode using 5 pixels. See: [[erode]].
sourceraw docstring

filter-channelclj

(filter-channel f)
(filter-channel f ch target p)

Filter one channel, write result into target.

This is helper function to create own filters.

Function parameter is channel value and should return new value.

Filter one channel, write result into target.

This is helper function to create own filters.

Function parameter is channel value and should return new value.
sourceraw docstring

filter-channel-xyclj

(filter-channel-xy f)
(filter-channel-xy f ch target p)

Filter one channel, write result into target.

This is helper function to create own filter.

Function parameters are: channel, pixels, x and y position.

Note: channel is first parameter.

Filter one channel, write result into target.

This is helper function to create own filter.

Function parameters are: channel, pixels, x and y position.

Note: channel is first parameter.
sourceraw docstring

filter-channelsclj

(filter-channels f p)
(filter-channels f do-alpha? p)
(filter-channels f0 f1 f2 f3 p)

Filter channels parallelly with filtering function. Build filtering function using filter-channel or filter-channel-xy helpers as with filter aplied partially. Filtering function parameters are: channel, target and source pixels.

When you pass one filter, three RGB channels will be processed (arity: 2). To enable alpha set do-alpha parameter to true (arity: 3). You can also use different filter for every channel separately (arity 5). Set nil to skip particular channel.

Filter channels parallelly with filtering function. Build filtering function using `filter-channel` or `filter-channel-xy` helpers as with filter aplied partially. Filtering function parameters are: channel, target and source pixels.

When you pass one filter, three RGB channels will be processed (arity: 2). To enable alpha set `do-alpha` parameter to `true` (arity: 3). You can also use different filter for every channel separately (arity 5). Set `nil` to skip particular channel.
sourceraw docstring

filter-colorsclj

(filter-colors f p)

Filter colors.

Filtering function should accept color and return color.

Filter colors.

Filtering function should accept color and return color.
sourceraw docstring

filter-colors-xyclj

(filter-colors-xy f p)

Filter colors.

Filtering function should accept Pixels, position as x,y values and return color

Filter colors.

Filtering function should accept Pixels, position as x,y values and return color
sourceraw docstring

gaussian-blurclj

(gaussian-blur radius)

Create gaussian blur for given radius.

Create gaussian blur for given radius.
sourceraw docstring

gaussian-blur-1clj

source

gaussian-blur-2clj

source

gaussian-blur-3clj

source

gaussian-blur-5clj

source

get-channelclj

(get-channel pixels ch)

Return whole ints array with chosen channel

Return whole `ints` array with chosen channel
sourceraw docstring

get-colorclj

(get-color pixels idx)
(get-color pixels x y)

Get color by index or position. In case of low density rendering returns current average color without alpha value.

Get color by index or position. In case of low density rendering returns current average color without alpha value.
sourceraw docstring

get-pixelclj

(get-pixel r x y)

Get pixel (color) from renderer buffer

Get pixel (color) from renderer buffer
sourceraw docstring

get-valueclj

(get-value pixels ch idx)
(get-value pixels ch x y)

Get channel value by index or position.

Get channel value by index or position.
sourceraw docstring

gradient-rendererclj

(gradient-renderer w h)
(gradient-renderer w h filter)
(gradient-renderer w h filter filter-radius & filter-params)

Create gradient renderer.

Optionally you can pass antialiasing filter and its parameters. Defaults to :none.

Create gradient renderer.

Optionally you can pass antialiasing filter and its parameters. Defaults to `:none`.
sourceraw docstring

horizontal-blurclj

(horizontal-blur radius)

Create horizontal blur for given radius.

Create horizontal blur for given radius.
sourceraw docstring

horizontal-blur-1clj

source

horizontal-blur-2clj

source

horizontal-blur-3clj

source

horizontal-blur-5clj

source

load-pixelsclj

(load-pixels n)

Load Pixels from file.

Load `Pixels` from file.
sourceraw docstring

medianclj

Median filter

Median filter
sourceraw docstring

merge-gradient-renderersclj

(merge-gradient-renderers target & renderers)

Merge gradient renderers and store result to the target.

Use this function to merge separate rendereing results (ex. from separeted threads).

This is mutating function. Data from list of renderers is added to the target.

Merge gradient renderers and store result to the target.

Use this function to merge separate rendereing results (ex. from separeted threads).

This is mutating function. Data from list of renderers is added to the target.
sourceraw docstring

merge-renderersclj

(merge-renderers target & renderers)

Paralelly merge renderers and store result to the target.

Use this function to merge separate rendereing results (ex. from separeted threads).

This is mutating function. Data from list of renderers is added to the target.

Paralelly merge renderers and store result to the target.

Use this function to merge separate rendereing results (ex. from separeted threads).

This is mutating function. Data from list of renderers is added to the target.
sourceraw docstring

modulateclj

(modulate amt)

Create modulate channel values filter.

Great to work with hue based color spaces.

Values from [0-2].

Create modulate channel values filter.

Great to work with hue based color spaces.

Values from [0-2].
sourceraw docstring

negateclj

(negate ch target p)

Negate filer.

Negate filer.
sourceraw docstring

normalizeclj

(normalize ch target p)

Normalize channel values to full range.

Normalize channel values to full range.
sourceraw docstring

pixelsclj

(pixels w h)
(pixels a w h)

Create empty Pixels object with [w,h] dimensions.

Optionally you can pass ints array a as a buffer. Size of array should be (* 4 w h).

Create empty `Pixels` object with [w,h] dimensions.

Optionally you can pass `ints` array `a` as a buffer. Size of array should be `(* 4 w h)`.
sourceraw docstring

posterizeclj

(posterize levels)

Create posterize filter for given radius.

Create posterize filter for given radius.
sourceraw docstring

posterize-16clj

source

posterize-4clj

source

posterize-8clj

source

quantile-1clj

Quantile (2/9) filter

Quantile (2/9) filter
sourceraw docstring

quantile-2clj

Quantile (3/9) filter

Quantile (3/9) filter
sourceraw docstring

quantile-3clj

Quantile (4/9) filter

Quantile (4/9) filter
sourceraw docstring

quantile-5clj

Quantile (6/9) filter

Quantile (6/9) filter
sourceraw docstring

quantile-6clj

Quantile (7/9) filter

Quantile (7/9) filter
sourceraw docstring

quantile-7clj

Quantile (8/9) filter

Quantile (8/9) filter
sourceraw docstring

rendererclj

(renderer w h)
(renderer w h filter)
(renderer w h filter filter-radius & filter-params)

Create renderer.

Optionally you can pass antialiasing filter and its parameters. Defaults to :none.

Create renderer.

Optionally you can pass antialiasing filter and its parameters. Defaults to `:none`.
sourceraw docstring

set-canvas-pixels!clj

(set-canvas-pixels! canvas p)
(set-canvas-pixels! canvas x y p)

Set Pixels to canvas. See set-image-pixels!.

Set `Pixels` to canvas. See [[set-image-pixels!]].
sourceraw docstring

set-channel!clj

(set-channel! pixels ch v)

Set whole channel (as ints array)

Set whole channel (as `ints` array)
sourceraw docstring

set-color!clj

(set-color! pixels idx v)
(set-color! pixels x y v)

Set color value by index or position

Set color value by index or position
sourceraw docstring

set-image-pixels!clj

(set-image-pixels! b p)
(set-image-pixels! b x y pin)

Set Pixels to image, mutating it.

Optionally you can set position when Pixels object has smaller size.

Set `Pixels` to image, mutating it.

Optionally you can set position when Pixels object has smaller size.
sourceraw docstring

set-renderer-scaling-factor!clj

(set-renderer-scaling-factor! renderer scale)
(set-renderer-scaling-factor! renderer ch1-scale ch2-scale ch3-scale)

Changes internal representation of density renderer values.

By default each channel is divided by 255.0 (and later multiplied by 255.0). Other values can be used to scale down and up other than RGB color ranges.

The main goal is to store values from 0.0 to 1.0.

Changes internal representation of density renderer values.

By default each channel is divided by 255.0 (and later multiplied by 255.0). Other values can be used to scale down and up other than RGB color ranges.

The main goal is to store values from `0.0` to `1.0`.
sourceraw docstring

set-value!clj

(set-value! pixels ch idx v)
(set-value! pixels ch x y v)

Set channel value by index or position

Set channel value by index or position
sourceraw docstring

solarizeclj

(solarize ch target p)

Solarize filter.

Solarize filter.
sourceraw docstring

thresholdclj

(threshold amount)
(threshold amount-low amount-high)

Create threshold filter.

You can pass amount from 0-1. or range.

Note if you want b&w result first convert to gray color.

Create threshold filter.

You can pass `amount` from 0-1. or range.

Note if you want b&w result first convert to gray color.
sourceraw docstring

threshold-25clj

source

threshold-50clj

source

threshold-75clj

source

tintclj

(tint col)
(tint col-low col-high)
(tint col-low col-mid col-high)

Create tinting filter.

  • one color - tint
  • two colors - interpolate between col-low for black and col-high for white.
  • three colors - like above but uses also mid-color for mid tones.
Create tinting filter.

* one color - tint
* two colors - interpolate between `col-low` for black and `col-high` for white.
* three colors - like above but uses also `mid-color` for mid tones.
sourceraw docstring

to-pixelsclj

(to-pixels pixels)
(to-pixels pixels cfg)
(to-pixels pixels x y w h)

Convert to Pixels. For low density rendering provide configuration. Works with Image/Canvas/Window and low density renderer.

Convert to Pixels. For low density rendering provide configuration. Works with Image/Canvas/Window and low density renderer.
sourceraw docstring

vertical-blurclj

(vertical-blur radius)

Create vertical blur for given radius.

Create vertical blur for given radius.
sourceraw docstring

vertical-blur-1clj

source

vertical-blur-2clj

source

vertical-blur-3clj

source

vertical-blur-5clj

source

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close