pxlsrt
Pixel sorter written in Ruby. On RubyGems. (Also available for JRuby and Node.js).
Installation
Requires the installation of Ruby (I use 2.0.0). All commands should be run through the Ruby command line.
gem install pxlsrt
Dependencies
- Ruby
- oily_png (
gem install oily_png
if you don't use bundler) - Thor (
gem install thor
if you don't use bundler)
Brute sort
Brute sorting uses a user defined range for bandwidths to sort.
pxlsrt brute INPUT OUTPUT [--min MIN] [--max MAX] [--vertical] [--smooth] [--reverse [either]] [--method [sum-rgb | red | green | blue | sum-hsb | hue | saturation | brightness | uniqueness | luma | random | magenta | cyan | yellow | alpha | none | sum-rgba | sum-hsba]] [--diagonal] [--verbose] [--middle [integer]]
Options and parameters
INPUT
(required string) - PNG image that is to be sorted.OUTPUT
(required string) - PNG image that is to be output to. Image does not need to exist.--min MIN
(optional integer) - Minimum length of bandwidth, 1 to infinity. If the length is greater than the dimension of the image, the minimum length is the dimension. Defaults toInfinity
.--max MAX
(optiona; integer) - Maximum length of bandwidth, 1 to infinity. If the length is greater than the dimension of the image, the maximum length is the dimension. Defaults toInfinity
.--vertical
or-v
(optional boolean) - Sorts vertically instead of horizontally. Defaults tofalse
.--smooth
or-s
(optional boolean) - Places identical pixels adjacent to each other within the band. Here's why this may be needed. Within a band are the following colors: rgb(0, 255, 0), rgb(0, 0, 0), rgb(0, 255, 0). If you sort by the red value, they will all be in the same area because their red values are all 0. However, they will be arranged into the area as they are ordered in the list. If the band is smoothed, the two rgb(0, 255, 0) pixels will be next to each other. Smoothing does not affect values outside of the band. Defaults tofalse
.--reverse
or-r
(optional string) - Use just--reverse
or-r
to reverse the bands. Use--reverse either
to randomly reverse bands. Do not use if you don't want to reverse.--method METHOD
or-m METHOD
(optional string) - Sets the method used to sort the band. In a different section are descriptions of each method. Defaults tosum-rgb
.--diagonal
or-d
(optional boolean) - Sorts pixels diagonally. To reverse the direction of the diagonal, use with--vertical
. Defaults tofalse
.--verbose
or-V
(optional boolean) - Prints to the terminal what the program is currently doing. Defaults tofalse
.--middle
or-M
(optional boolean or integer) - Has it sorted from the middle out, kind of like a sunrise gradient. Enter in a positive or negative integer n and it will "middlate" |n| times (if n is negative, it will work backwards). Leave blank to "middlate" once. Defaults tofalse
.
Examples
Bare minimum
pxlsrt brute input.png output.png
Pixel sorts input.png
horizontally by the sum of its red, green, and blue values with bandwidths across the size width of the image, does not smooth, does not reverse, and outputs to output.png
.
Full suite example
pxlsrt brute input.png output.png --min 20 --max 30 --vertical --smooth --reverse --method hue
Pixel sorts input.png
vertically by hue with bandwidths from 20 to 30, smoothes it, reverses direction, and outputs to output.png
.
Full suite shortcut example
pxlsrt brute input.png output.png --min 20 --max 30 -v -s -r -m hue
Same as above example.
Smart sort
Smart sorting uses edges detected within the image (determined through Sobel operators) along with a user-defined threshold to define bandwidths to sort.
pxlsrt smart INPUT OUTPUT [--threshold THRESHOLD] [--absolute] [--vertical] [--smooth] [--reverse [either]] [--method [sum-rgb | red | green | blue | sum-hsb | hue | saturation | brightness | uniqueness | luma | random | magenta | cyan | yellow | alpha | none | sum-rgba | sum-hsba]] [--diagonal] [--verbose] [--middle [integer]]
Options and parameters
Options that are shared with the brute method are covered there.
--threshold THRESHOLD
or-t THRESHOLD
(optional integer) - Used for edge finding. Defaults to20
.--absolute
or-a
(optional boolean) - A different method for edge finding. Defaults tofalse
.
Kim sort
This uses Kim Asendorf's pixel sorting algorithm.
pxlsrt kim INPUT OUTPUT [--method METHOD] [--value VALUE] [--verbose]
--method METHOD
or-m METHOD
(optional string) - The method to use for sorting. Kim Asendorf's algorithm only uses three methods:black
,brightness
, andwhite
. Defaults tobrightness
.--value VALUE
or-v VALUE
(optional integer) - Used in the algorithm to find the next pixel to break at. Default depends on chosen method.--verbose
or-V
Seed sort
Inspired by Jeff Thompson's seed sorter, but only employs portions of their algorithm.
pxlsrt seed INPUT OUTPUT [--threshold THRESHOLD] [--smooth] [--reverse [either]] [--method [sum-rgb | red | green | blue | sum-hsb | hue | saturation | brightness | uniqueness | luma | random | magenta | cyan | yellow | alpha | none | sum-rgba | sum-hsba]] [--verbose] [--middle [integer]] [--random SEEDCOUNT] [--distance DISTANCE]
--random SEEDCOUNT
or-R SEEDCOUNT
(optional) - Opt to use random seed placement instead of placing seeds based on edge finding. TheSEEDCOUNT
should either befalse
, for the edge finding method, or an integer corresponding to how many seeds to place. Defaults tofalse
, (edge finding method).--threshold THRESHOLD
or-t THRESHOLD
(optional number) - Used only with edge finding method. The threshold to determine edges to use as seeds. The smaller the number, the less seeds. Defaults to0.1
.--distance DISTANCE
or-d DISTANCE
(optional) - Used only with edge finding method. The minimum number of pixels away that seeds have to be away from each other. Will weed out infringing seeds. Inputtingfalse
is equivalent to not removing any seeds that are close to each other. Defaults to100
.- The rest are the same as what is used in Brute and Smart.
Brute, Smart, and Seed sorting methods
sum-rgb
Sorts by the sum of the red, green, and blue values of the pixels.
sum-rgb(red, green, blue) = red + green + blue
red
Sorts by the red value of the pixels.
red(red, green, blue) = red
green
Sorts by the green value of the pixels.
green(red, green, blue) = green
blue
Sorts by the blue value of the pixels.
blue(red, green, blue) = blue
sum-hsb
Creates a sum of the hue, saturation, and brightness values of the pixel and sorts by that. The smoothing option is suggested for this method.
sum-hsb(hue, saturation, brightness) = (hue * 100 / 360) + saturation + brightness
hue
Sorts by the hue value of the pixels, creating something like a rainbow. The smoothing option is suggested for this method.
hue(hue, saturation, brightness) = hue
saturation
Sorts by the saturation value of the pixels, creating an effect like the bands are fading to grey. The smoothing option is suggested for this method.
saturation(hue, saturation, brightness) = saturation
brightness
Sorts by the brightness value of the pixels. Produces a similar result to sum-rgb, but not exactly the same.
brightness(hue, saturation, brightness) = brightness
uniqueness
Sorts by the "distance" of the pixel from the average color of band (excluding the pixel being determined).
avg(colors) = sum(colors) / (length of colors)
uniqueness(red, green, blue, alpha, reds, greens, blues, alphas) = sqrt((red - avg(reds))^2 + (green - avg(greens))^2 + (blue - avg(blues))^2 + (alpha - avg(alphas))^2)
luma
Sorts by human color perception (similar to brightness and sum-rgb).
luma(red, green, blue) = red * 0.2126 + green * 0.7152 + blue * 0.0722
random
Randomizes the pixels.
magenta
Sorts by a magenta value.
magenta(red, green, blue) = red + blue
cyan
Sorts by a cyan value.
cyan(red, green, blue) = green + blue
yellow
Sorts by a yellow value.
yellow(red, green, blue) = red + green
alpha
Sorts by the opacity (the opposite of transparency) of a pixel. The "A" in RGBA.
alpha(red, green, blue, alpha) = alpha
sum-rgba
Sorts by the sum of the red, green, blue, and alpha values.
sum-rgba(red, green, blue, alpha) = red + green + blue + alpha
sum-hsba
Sorts by the sum of the hue, saturation, brightness, and alpha values.
sum-hsba(hue, saturation, brightness, alpha) = (hue * 100 / 360) + saturation + brightness + alpha * 100 / 255
none
Doesn't do anything to the band. You may think this is useless but if you use it with reverse and/or middlation it can create some cool effects.
To use within Ruby files
require 'pxlsrt'
Pxlsrt::Smart, Pxlsrt::Brute, Pxlsrt::Kim, Pxlsrt::Seed
Pxlsrt::Brute.brute, Pxlsrt::Smart.smart, Pxlsrt::Kim.kim, or Pxlsrt::Seed.seed
Pxlsrt::Brute.brute(input, options)
Pxlsrt::Smart.smart(input, options)
Pxlsrt::Kim.kim(input, options)
Pxlsrt::Seed.seed(input, options)
input
(required string or ChunkyPNG::Image) - Either a ChunkyPNG image or a string of a path leading to an image.options
(optional hash) - A hash of options (the same as gone over above). Includes the option of:trusted
, which bypasses the need to check if the options match the rules.
Example:
img=ChunkyPNG::Image.from_file("path/to/image")
sorted_img=Pxlsrt::Brute.brute(img, :verbose=>true, :min=>20, :diagonal=>true)
sorted_img.save("path/to/output")
img=ChunkyPNG::Image.from_file("path/to/image")
sorted_img=Pxlsrt::Smart.smart(img, :verbose=>true, :diagonal=>true)
sorted_img.save("path/to/output")
img=ChunkyPNG::Image.from_file("path/to/image")
sorted_img=Pxlsrt::Kim.kim(img, :verbose=>true, :method=>"black")
sorted_img.save("path/to/output")
img=ChunkyPNG::Image.from_file("path/to/image")
sorted_img=Pxlsrt::Seed.seed(img, :verbose=>true, :middlate => 10)
sorted_img.save("path/to/output")
Alternatively:
Pxlsrt::Brute.brute("path/to/image", :verbose=>true, :min=>20, :diagonal=>true).save("path/to/output")
Pxlsrt::Smart.smart("path/to/image", :verbose=>true, :diagonal=>true).save("path/to/output")
Pxlsrt::Kim.kim("path/to/image", :verbose=>true, :method=>"black").save("path/to/output")
Pxlsrt::Seed.seed(img, :verbose=>true, :middlate => 10).save("path/to/output")
Pxlsrt::Brute.suite, Pxlsrt::Smart.suite, Pxlsrt::Kim.suite, or Pxlsrt::Seed.suite
Pxlsrt::Brute.suite(inputFileName, outputFileName, options)
Pxlsrt::Smart.suite(inputFileName, outputFileName, options)
Pxlsrt::Kim.suite(inputFileName, outputFileName, options)
Pxlsrt::Seed.suite(inputFileName, outputFileName, options)
inputFileName
(required string) - Path to input image.outputFileName
(required string) - Path to output image.options
(optional hash) - A hash of options (the same as gone over above). Includes the option of:trusted
, which bypasses the need to check if the options match the rules.
Example:
Pxlsrt::Brute.suite("path/to/image", "path/to/output", :verbose=>true, :min=>20, :diagonal=>true)
Pxlsrt::Smart.suite("path/to/image", "path/to/output", :verbose=>true, :diagonal=>true)
Pxlsrt::Kim.suite("path/to/image", "path/to/output", :verbose=>true, :method=>"black")
Pxlsrt::Seed.suite("path/to/image", "path/to/output", :verbose=>true, :middlate => 10)