crystal-image

Common foundation types for Crystal's image ecosystem. Provides standard color types, pixel formats, and geometry primitives that image libraries can build upon.

Installation

Add this to your application's shard.yml:

dependencies:
  image:
    github: crystal-community/crystal-image

Usage

require "image"

# Create images using factory methods
img = Image.rgba(640, 480)
gray_img = Image.gray(320, 240)

# Create colors
red = Image::Color.rgba(255, 0, 0, 255)
gray = Image::Color.gray(128)

# Set and get pixels
img[10, 20] = red
pixel = img[10, 20]

# Sub-image slicing (using ranges)
# Returns a view sharing the same memory (fast)
sub = img[10..50, 20...60]
sub.fill(red) # Fills the sub-region in the original image

# Iterators (Ergonomic pixel loops)
img.each_pixel do |pixel, x, y|
  # Read pixel with coordinates
end

# In-place modification
img.map! do |pixel|
  pixel # Return new pixel value here
end

# Bulk Operations
img.fill(Image::Color::RGBA8.new(0, 0, 0, 0)) # Clear image

# Geometry operations
rect = Image.rect(0, 0, 100, 100)
point = Image.point(50, 50)
runion = rect.union(Image.rect(50, 50, 150, 150))

Image Types

All image types implement the PixelBuffer(T) interface:

• RGBA8 - 8-bit RGBA with premultiplied alpha (4 bytes/pixel)
• NRGBA8 - 8-bit RGBA with non-premultiplied alpha (4 bytes/pixel)
• Gray8 - 8-bit grayscale (1 byte/pixel)
• RGBA16 - 16-bit RGBA with premultiplied alpha (8 bytes/pixel)
• NRGBA16 - 16-bit RGBA with non-premultiplied alpha (8 bytes/pixel)
• Gray16 - 16-bit grayscale (2 bytes/pixel)
• Uniform(T) - Memory-efficient solid color images

Color Types

8-bit Colors

• RGBA8 - Premultiplied alpha (0 ≤ r,g,b ≤ a ≤ 255)
• NRGBA8 - Non-premultiplied alpha
• RGB8 - No alpha channel
• Gray8 - Grayscale
• Alpha8 - Alpha only

16-bit Colors

• RGBA16 - Premultiplied alpha (0 ≤ r,g,b ≤ a ≤ 65535)
• NRGBA16 - Non-premultiplied alpha
• RGB16 - No alpha channel
• Gray16 - Grayscale
• Alpha16 - Alpha only

Alternative Color Spaces

• YCbCr8 - Y'CbCr color space (JPEG/video)
• NYCbCrA8 - Y'CbCr with alpha
• CMYK8 - CMYK for printing
• HSL - Hue, Saturation, Lightness
• HSV - Hue, Saturation, Value
• LAB - CIELAB perceptually uniform color space

Geometry Types

• Point - 2D integer coordinates with arithmetic operations
• Rectangle - Axis-aligned rectangle with set operations

# Points
p1 = Image.point(10, 20)
p2 = Image.point(5, 15)
p3 = p1 + p2  # Point(15, 35)

# Rectangles
r1 = Image.rect(0, 0, 100, 100)
r2 = Image.rect(50, 50, 150, 150)

r1.width                    # 100
r1.height                   # 100
r1.inset(10)               # Shrink by 10 pixels
r1.intersect(r2)           # Overlapping region
r1.union(r2)               # Bounding box
r1.overlaps?(r2)           # true
p1.in?(r1)                 # true if point inside rect

Contributing

1. Fork it (https://github.com/crystal-community/crystal-image/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Ali Naqvi - creator and maintainer