Echostorm.SharpImage 1.0.2

SharpImage

A pure C# .NET 10 port of ImageMagick. Zero native dependencies. Full AOT compatibility. No P/Invoke, no C/C++ bindings — just managed code competing at native speed.

Why SharpImage?

ImageMagick is the gold standard for image processing, but it's written in C — a language that has allowed memory corruption, buffer overflows, and CVEs to accumulate for decades. .NET 10 has matured to the point where C# can compete with C and C++ in raw performance when used with care: Span<T>, hardware intrinsics (SSE2/SSE4.1/AVX2/AVX-512), stackalloc, ArrayPool<T>, and aggressive JIT inlining.

SharpImage reimplements ImageMagick's image processing pipeline entirely in safe, managed C# and with better performance — producing a library DLL, a CLI tool, and a GUI Photoshop style example project.

Features

34 Image Formats (Including 31 Camera Raw)

Camera raw support is decode-only for proprietary formats (Canon, Nikon, Sony, etc.) and decode+encode for DNG. Three demosaicing algorithms are available: Bilinear (fast), VNG (quality), and AHD (highest quality). Fujifilm X-Trans 6×6 CFA is also supported.

40+ Colorspaces

sRGB, Linear RGB, scRGB, Adobe98, ProPhoto, Display P3, Lab, LCHab, LCHuv, Luv, OkLab, OkLCH, Jzazbz, XYZ, xyY, LMS, CAT02 LMS, HSL, HSV, HSB, HSI, HCL, HCLp, HWB, CMY, CMYK, YCbCr (Rec.601 & Rec.709), YCC, YDbDr, YIQ, YPbPr, YUV, OHTA, Gray, Linear Gray, Log, Transparent

23 Resize Methods

Nearest Neighbor · Bilinear · Bicubic · Lanczos2/3/4/5 · Mitchell · Catrom · Hermite · Triangle · Gaussian · Spline · Sinc · Hann · Hamming · Blackman · Kaiser · Parzen · Bohman · Welch · Bartlett · Lagrange

29 Composite Blend Modes

Over · Multiply · Screen · Overlay · Darken · Lighten · ColorDodge · ColorBurn · HardLight · SoftLight · Difference · Exclusion · Add · Subtract · Plus · Minus · Dissolve · Bumpmap · Atop · In · Out · Xor · HardMix · VividLight · LinearLight · PinLight · ModulusAdd · ModulusSubtract · Replace

170+ Effects & Operations

Performance

Benchmarks on .NET 10.0.3 with AVX-512, ShortRun (BenchmarkDotNet):

Design Principles

• Zero-allocation hot paths — Span<T>, stackalloc, and ArrayPool<T> keep the GC out of per-pixel work
• SIMD everywhere — Resize, blur, compositing, and pixel conversion use Vector256/Vector128 with FMA where available
• Branchless arithmetic — Critical inner loops avoid conditional branching
• Bounds-check elimination — Span iteration patterns that let the JIT remove safety checks
• Cache-friendly layout — Row-major pixel storage with struct-based pixel types

Getting Started

Requirements

• .NET 10 SDK or later

Install via NuGet

dotnet add package Echostorm.SharpImage

Or via the Package Manager Console:

Install-Package Echostorm.SharpImage

Build from Source

git clone https://github.com/Echostorm44/SharpImage.git
cd SharpImage
dotnet build -c Release

Run TUnit Tests

The test suite uses TUnit with 1,600+ tests covering formats, colorspaces, transforms, effects, compositing, and edge cases.

# Run the full test suite
dotnet run --project tests/SharpImage.Tests -c Release

# Run tests matching a filter
dotnet run --project tests/SharpImage.Tests -c Release -- --filter "*Png*"

Run BigTest

BigTest is an integration harness that invokes the SharpImage CLI and compares output against ImageMagick. It requires a published AOT build of the CLI first.

# 1. Publish the CLI (AOT)
dotnet publish src/SharpImage.Cli -c Release

# 2. Run BigTest
dotnet run --project tests/SharpImage.BigTest -c Release

Run Benchmarks

Performance benchmarks use BenchmarkDotNet. Always run in Release mode — Debug builds produce meaningless numbers.

# Run all benchmarks
dotnet run --project benchmarks/SharpImage.Benchmarks -c Release

# Run a specific benchmark class or filter
dotnet run --project benchmarks/SharpImage.Benchmarks -c Release -- --filter *Resize*

# List available benchmarks without running them
dotnet run --project benchmarks/SharpImage.Benchmarks -c Release -- --list flat

Tip: Close other applications during benchmark runs for stable results. BenchmarkDotNet will report mean, median, and allocation statistics automatically.

CLI Usage

# Convert between formats
dotnet run --project src/SharpImage.Cli -- convert photo.jpg photo.png

# Convert camera raw to PNG (with demosaic algorithm selection)
dotnet run --project src/SharpImage.Cli -- convert photo.cr2 photo.png
dotnet run --project src/SharpImage.Cli -- convert photo.nef output.tiff --demosaic ahd

# Display camera raw metadata
dotnet run --project src/SharpImage.Cli -- rawinfo photo.cr2

# Resize an image
dotnet run --project src/SharpImage.Cli -- resize photo.jpg -w 800 -h 600 resized.png

# Apply Gaussian blur
dotnet run --project src/SharpImage.Cli -- blur photo.jpg --sigma 3.0 blurred.png

# Composite two images
dotnet run --project src/SharpImage.Cli -- composite background.png overlay.png --mode multiply result.png

# Compare two images
dotnet run --project src/SharpImage.Cli -- compare original.png modified.png --diff difference.png

# Sharpen
dotnet run --project src/SharpImage.Cli -- sharpen photo.jpg --sigma 1.0 --amount 2.0 sharp.png

# See all commands
dotnet run --project src/SharpImage.Cli -- --help

Or publish AOT and use directly:

dotnet publish src/SharpImage.Cli -c Release
# Then use the native binary:
sharpimage convert photo.jpg photo.png
sharpimage convert photo.cr2 developed.tiff --demosaic ahd
sharpimage rawinfo photo.nef

Use as a Library

Add a project reference to src/SharpImage/SharpImage.csproj:

using SharpImage.Image;
using SharpImage.Transform;
using SharpImage.Formats;

// Load an image
using var stream = File.OpenRead("photo.jpg");
var frame = JpegCoder.Read(stream);

// Resize with Lanczos3
var resized = Resize.Apply(frame, 800, 600, InterpolationMethod.Lanczos3);

// Save as PNG
using var output = File.Create("resized.png");
PngCoder.Write(resized, output);

Camera Raw Decode

using SharpImage.Formats;

// Decode a camera raw file with specific options
byte[] rawData = File.ReadAllBytes("photo.cr2");
var options = new CameraRawDecodeOptions { Algorithm = DemosaicAlgorithm.AHD };
var frame = CameraRawCoder.Decode(rawData, options);

// Inspect raw metadata without decoding
var metadata = CameraRawCoder.GetMetadata(rawData);
Console.WriteLine($"{metadata.Make} {metadata.Model} — {metadata.SensorWidth}×{metadata.SensorHeight}");

// Save as DNG (the only raw format that supports encode)
byte[] dngData = CameraRawCoder.Encode(frame);
File.WriteAllBytes("output.dng", dngData);

Architecture

SharpImage/
├── src/
│   ├── SharpImage/                 # Core library (DLL)
│   │   ├── Core/                   # Quantum, PixelTypes, Geometry, MemoryPool
│   │   ├── Image/                  # ImageFrame, PixelCache, CacheView, ImageList
│   │   ├── Colorspaces/            # 40+ colorspace converters
│   │   ├── Formats/                # 34 format families (incl. 31 camera raw)
│   │   │   ├── CameraRawCoder.cs   # Camera raw decode/encode (CR2, NEF, ARW, DNG, ...)
│   │   │   ├── CameraRawFormats.cs  # Per-format parsers (11 dedicated + generic)
│   │   │   ├── BayerDemosaic.cs     # Bilinear/VNG/AHD + X-Trans demosaic
│   │   │   └── ...                  # 30+ other format coders
│   │   ├── Transform/              # Resize, Crop, Rotate, Distort, SeamCarving
│   │   ├── Effects/                # 19 effect categories, 170+ operations
│   │   ├── Enhance/                # Equalize, Normalize, CLAHE, Curves, etc.
│   │   ├── Composite/              # 29 blend modes
│   │   ├── Analysis/               # Edge detection, hashing, segmentation
│   │   ├── Fourier/                # FFT forward/inverse
│   │   ├── Draw/                   # Primitives, text, paths
│   │   ├── Morphology/             # Erode, Dilate, Skeleton, Hit-and-Miss
│   │   └── Channel/                # Channel operations, separation, combining
│   └── SharpImage.Cli/             # Command-line interface (228 commands)
├── tests/
│   └── SharpImage.Tests/           # 1,600+ tests (TUnit framework)
└── benchmarks/
    └── SharpImage.Benchmarks/      # BenchmarkDotNet performance suite

Key Types

Pixel Storage

• 16-bit quantum (ushort per channel) — matches ImageMagick's high-quality internal representation
• Row-major layout — pixels stored in contiguous rows for cache efficiency
• 3 or 4 channels — RGB or RGBA, interleaved per pixel
• Large image support — automatic disk-backed pixel cache for images exceeding memory limits

Testing

The test suite uses TUnit and covers:

• Format round-trips — encode→decode→compare for all 34 format families
• Camera raw decode — real-file tests for CR2, DNG, NEF, ORF, PEF, RAF, RW2 with metadata and pixel verification
• Colorspace accuracy — forward→inverse conversion for all 40+ colorspaces
• Transform correctness — pixel-perfect verification of flip, flop, rotate, crop, resize (all 23 methods)
• Edge cases — 1×1 images, 16384×1 strips, all-black/white, fully transparent, extreme resize ratios, odd/prime dimensions, 16-bit quantum extremes
• Effect coverage — each effect tested with multiple parameter combinations
• Composite math — blend mode output verified against manual calculations

Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all existing tests pass: dotnet run --project tests/SharpImage.Tests -c Release
5. Run benchmarks to check for regressions: dotnet run --project benchmarks/SharpImage.Benchmarks -c Release -- --filter *YourArea*
6. Submit a pull request

Code Style

• PascalCase for public members, types, methods, properties
• camelCase for local variables and private fields
• Prefer struct over class for small data types
• Use Span<T> and stackalloc in hot paths
• No dependency injection — direct static method calls
• Keep files focused but don't create separate files for small DTOs

License

Licensed under the Apache License 2.0.

Acknowledgments

• ImageMagick — the project that defined image processing for decades. SharpImage is a clean-room reimplementation inspired by ImageMagick's feature set and algorithms.
• TUnit — modern .NET test framework
• BenchmarkDotNet — precise .NET benchmarking
• Spectre.Console — beautiful CLI output