pixel-sorting

Pixel Sorting

ASDF-style pixel sorting implementation in Python with extended features. Based on Kim Asendorf's original Processing sketch from 2010, with additional modes inspired by satyarth/pixelsort.

What is Pixel Sorting?

Pixel sorting is a glitch art technique that rearranges pixels in an image based on certain criteria (brightness, hue, saturation, etc.) within defined intervals. This creates distinctive visual effects ranging from subtle distortions to dramatic abstract transformations.

Installation

As a CLI tool

This project uses uv for dependency management. Dependencies will be installed automatically when you run the script.

As a library

Install using pip:

pip install git+https://github.com/rockerBOO/pixel-sorting.git

Or with uv:

uv pip install git+https://github.com/rockerBOO/pixel-sorting.git

For ComfyUI

Clone directly into your ComfyUI custom_nodes directory:

cd ComfyUI/custom_nodes/
git clone https://github.com/rockerBOO/pixel-sorting.git
cd pixel-sorting
pip install -e .

The nodes will be automatically available after restarting ComfyUI.

See COMFYUI_SETUP.md for detailed ComfyUI installation and usage instructions.

Quick Start

Command Line

# Analyze an image to find good thresholds
uv run python main.py your_image.jpg --analyze

# Sort with ASDF bright mode
uv run python main.py your_image.jpg --interval bright

# Sort with random intervals and hue sorting
uv run python main.py your_image.jpg --interval random --sort hue

As a Library

from PIL import Image
from pixelsort import pixelsort, analyze

# Load an image
img = Image.open("photo.jpg")

# Analyze to get suggested thresholds
stats = analyze(img)
print(f"Suggested bright threshold: {stats['suggestions']['bright']['subtle']}")

# Apply pixel sorting
result = pixelsort(
    img,
    interval='bright',
    sorting='hue',
    bright_value=stats['suggestions']['bright']['subtle']
)

# Save result
result.save("sorted.png")

See example_library.py for more usage examples.

Usage

Basic Command Structure

uv run python main.py INPUT [OPTIONS]

Image Analysis

Before sorting, analyze your image to find optimal thresholds:

uv run python main.py input.jpg --analyze

This displays:

• Brightness statistics (min, max, mean, median, percentiles)
• Pixel value statistics
• Suggested thresholds for each interval mode (subtle, moderate, aggressive)

Interval Modes

The --interval (or -i) flag controls WHERE pixels are sorted:

ASDF-style Threshold Modes

• bright - Sort pixels with brightness ≥ threshold (default: 127)

  uv run python main.py input.jpg --interval bright --bright-value 100
  

• dark - Sort pixels with brightness ≤ threshold (default: 223)

  uv run python main.py input.jpg --interval dark --dark-value 50
  

• white - Sort pixels with value ≥ threshold (default: -12345678)

  uv run python main.py input.jpg --interval white --white-value -10000000
  

• black - Sort pixels with value ≤ threshold (default: -3456789)

  uv run python main.py input.jpg --interval black --black-value -5000000
  

Extended Interval Modes

• threshold - Sort pixels between lower and upper brightness thresholds

  uv run python main.py input.jpg --interval threshold --lower-threshold 0.3 --upper-threshold 0.7
  

• random - Randomly generated intervals

  uv run python main.py input.jpg --interval random --char-length 100
  

• waves - Wave-like intervals of nearly uniform width

  uv run python main.py input.jpg --interval waves --char-length 75
  

• edges - Intervals defined by edge detection

  uv run python main.py input.jpg --interval edges --lower-threshold 0.2
  

• none - Sort entire rows (no interval boundaries)

  uv run python main.py input.jpg --interval none
  

Sorting Functions

The --sort (or -s) flag controls HOW pixels are sorted within intervals:

• value - ASDF-style pixel integer value (default)
• lightness - Sort by brightness/lightness (HLS)
• hue - Sort by hue (creates rainbow effects)
• saturation - Sort by color saturation
• intensity - Sort by sum of RGB values
• minimum - Sort by minimum RGB channel value

# Sort bright intervals by hue
uv run python main.py input.jpg --interval bright --sort hue

# Sort dark intervals by saturation
uv run python main.py input.jpg --interval dark --dark-value 60 --sort saturation

Additional Parameters

Angle Rotation

Sort at an angle (in degrees):

# Sort at 45 degrees
uv run python main.py input.jpg --interval bright --angle 45

# Sort at 90 degrees (vertical sorting)
uv run python main.py input.jpg --interval bright --angle 90

Randomness

Randomly skip sorting some intervals (0-100%):

# Skip 30% of intervals randomly
uv run python main.py input.jpg --interval bright --randomness 30

Multiple Passes

Apply sorting multiple times for stronger effects:

# Two passes
uv run python main.py input.jpg --interval bright --loops 2

Character Length

Control interval width for random and waves modes:

uv run python main.py input.jpg --interval random --char-length 150

Output Path

Specify output file:

uv run python main.py input.jpg --interval bright --output result.png

If not specified, output defaults to input_INTERVAL_SORT.png

Examples

Classic ASDF Effects

# Bright mode with default settings
uv run python main.py photo.jpg --interval bright

# Dark mode with custom threshold (use --analyze first to find good values)
uv run python main.py photo.jpg --interval dark --dark-value 50

# Two-pass sorting (sort vertically then horizontally like original ASDF)
uv run python main.py photo.jpg --interval bright --angle 90 --output temp.png
uv run python main.py temp.png --interval bright --output final.png

Creative Effects

# Rainbow sorting (hue-based)
uv run python main.py photo.jpg --interval bright --sort hue

# Random glitch with saturation sorting
uv run python main.py photo.jpg --interval random --char-length 80 --sort saturation

# Edge-detected intervals with lightness sorting
uv run python main.py photo.jpg --interval edges --lower-threshold 0.3 --sort lightness

# Diagonal sorting
uv run python main.py photo.jpg --interval bright --angle 45

# Chaotic random with high randomness
uv run python main.py photo.jpg --interval random --randomness 50 --char-length 100

Combining Multiple Options

# Complex example: diagonal bright intervals, sorted by hue, with 20% randomness
uv run python main.py photo.jpg --interval bright --bright-value 100 --sort hue --angle 45 --randomness 20

# Aggressive dark sorting with multiple passes
uv run python main.py photo.jpg --interval dark --dark-value 75 --loops 3

Complete Options Reference

positional arguments:
  input                 Input image path

optional arguments:
  -h, --help            Show help message
  --analyze             Analyze image and suggest thresholds (does not sort)

interval options:
  -i, --interval {threshold,bright,dark,white,black,random,waves,edges,none}
                        Interval function (default: bright)

sorting options:
  -s, --sort {lightness,hue,saturation,intensity,minimum,value}
                        Sorting function (default: value)

output options:
  -o, --output OUTPUT   Output image path

parameters:
  -a, --angle ANGLE     Angle in degrees (default: 0)
  -r, --randomness PCT  Randomness percentage 0-100 (default: 0)
  -c, --char-length N   Characteristic length for random/waves (default: 50)
  -l, --loops N         Number of sorting passes (default: 1)

threshold values:
  --lower-threshold FLOAT   Lower threshold 0-1 for threshold mode (default: 0.25)
  --upper-threshold FLOAT   Upper threshold 0-1 for threshold mode (default: 0.8)
  --white-value INT         White threshold for white mode (default: -12345678)
  --black-value INT         Black threshold for black mode (default: -3456789)
  --bright-value INT        Brightness threshold for bright mode (default: 127)
  --dark-value INT          Darkness threshold for dark mode (default: 223)

Tips & Tricks

1. Always analyze first - Run --analyze to find good thresholds for your specific image
2. Start subtle - Use the "subtle" suggested values from analysis for gentle effects
3. Dark/bright defaults are often wrong - The ASDF defaults (127, 223) work poorly on most images. Use --analyze to find better values.
4. Experiment with sorting functions - Try different combinations of interval modes and sorting functions
5. Angle 90 = vertical sorting - Use --angle 90 then --angle 0 for the classic ASDF two-pass effect
6. Randomness adds variation - Small randomness values (10-30%) can make effects more interesting

Recommended Threshold Ranges

Based on typical images:

• bright-value: 75-150 (sorts top 10-50% brightest pixels)
• dark-value: 30-80 (sorts bottom 10-40% darkest pixels)
• lower-threshold: 0.2-0.4 (for threshold mode)
• upper-threshold: 0.6-0.9 (for threshold mode)

How It Works

1. Interval Generation - The interval function divides each row into segments (intervals) that will or won't be sorted
2. Pixel Sorting - Pixels within each interval are sorted according to the sorting function
3. Randomness - Some intervals are randomly skipped (left unsorted) based on the randomness percentage
4. Rotation - The image can be rotated before/after sorting for diagonal effects
5. Multiple Passes - The process can be repeated multiple times for stronger effects

Library API

pixelsort()

Main function to sort pixels in an image.

pixelsort(
    image: Image.Image,
    interval: str | Callable = 'bright',
    sorting: str | Callable = 'value',
    angle: float = 0,
    randomness: float = 0,
    char_length: int = 50,
    loops: int = 1,
    lower_threshold: float = 0.25,
    upper_threshold: float = 0.8,
    white_value: int = -12345678,
    black_value: int = -3456789,
    bright_value: int = 127,
    dark_value: int = 223,
) -> Image.Image

Parameters:

• image - PIL Image to sort (will be converted to RGBA)
• interval - Interval function name or callable
  • Options: 'threshold', 'bright', 'dark', 'white', 'black', 'random', 'waves', 'edges', 'none'
• sorting - Sorting function name or callable
  • Options: 'lightness', 'hue', 'saturation', 'intensity', 'minimum', 'value'
• angle - Rotation angle in degrees (default: 0)
• randomness - Percentage of intervals to skip (0-100, default: 0)
• char_length - Characteristic length for random/waves modes (default: 50)
• loops - Number of sorting passes (default: 1)
• lower_threshold - Lower threshold for threshold mode (0-1, default: 0.25)
• upper_threshold - Upper threshold for threshold mode (0-1, default: 0.8)
• white_value - Threshold for white mode (default: -12345678)
• black_value - Threshold for black mode (default: -3456789)
• bright_value - Threshold for bright mode (0-255, default: 127)
• dark_value - Threshold for dark mode (0-255, default: 223)

Returns: PIL Image with sorted pixels

analyze()

Analyze image brightness distribution and suggest thresholds.

analyze(image: Image.Image) -> dict

Parameters:

• image - PIL Image to analyze

Returns: Dictionary containing:

• brightness_stats - min, max, mean, median, percentiles
• pixel_int_stats - min, max, median, percentiles
• suggestions - recommended thresholds for each mode
  • bright, dark, white, black - each with subtle, moderate, aggressive values

Example:

from PIL import Image
from pixelsort import pixelsort, analyze

img = Image.open("photo.jpg")

# Get suggested thresholds
stats = analyze(img)
bright_threshold = stats['suggestions']['bright']['subtle']

# Apply sorting
result = pixelsort(
    img,
    interval='bright',
    sorting='hue',
    bright_value=bright_threshold,
    randomness=10
)

result.save("output.png")

ComfyUI Integration

This package works out-of-the-box as a ComfyUI custom node.

Included nodes:

• PixelSorting - Main sorting node with all parameters exposed (found under image/effects)
• PixelSortAnalyze - Analyze images and output suggested thresholds (found under image/analysis)

Quick setup:

cd ComfyUI/custom_nodes/
git clone https://github.com/rockerBOO/pixel-sorting.git
cd pixel-sorting
pip install -e .
# Restart ComfyUI

Features:

• Proper tensor conversion between ComfyUI and PIL formats
• Batch processing support
• All interval and sorting modes available
• Direct output of analyzed threshold values to other nodes

For detailed ComfyUI usage, workflows, and troubleshooting, see COMFYUI_SETUP.md.

Credits

• Original ASDF Pixel Sort: Kim Asendorf (2010)
• Python implementation inspiration: satyarth/pixelsort