Recursive AI

Pixelate an image in C#

OneImage is a free, open-source image library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Pixelation turns a picture into a mosaic of square blocks without shrinking the canvas.

Terminal
dotnet add package RecursiveAI.OneImage

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneImage;
 
var image = Image.Load("grid.png");
image.Pixelate(size: 2).Save("mosaic.png");
Console.WriteLine("Wrote mosaic.png");

Unzip the example, then dotnet run.

Text
Wrote mosaic.png

grid.png is a generated 4×4 color grid in the download.

The full program

At column x and row y, the grid’s RGB values are (60 × x, 60 × y, 40 × (x + y)), with coordinates starting at zero.

C#
using OneImage;
 
var image = Image.Load("grid.png");
image.Pixelate(size: 2).Save("mosaic.png");
Console.WriteLine("Wrote mosaic.png");
 
var saved = Image.Load("mosaic.png");
var row = new Rgba32[4];
saved.CopyPixelsTo<Rgba32>(row, new ImageRect(0, 0, 4, 1));
Console.WriteLine($"Canvas: {saved.Width} x {saved.Height}");
foreach (int x in new[] { 0, 1, 2 })
    Console.WriteLine($"({x},0): {row[x].R},{row[x].G},{row[x].B}");

dotnet run prints:

Text
Wrote mosaic.png
Canvas: 4 x 4
(0,0): 60,60,80
(1,0): 60,60,80
(2,0): 180,60,160

The first two samples come from the same block. The third is from the next block. A size below 1 throws ArgumentOutOfRangeException.

Variations

Use larger blocks. On this tiny grid, a size of 4 covers the whole image with one block. Keep using OneImage; from the snippet at the top.

C#
Image.Load("grid.png").Pixelate(size: 4)
    .Save("mosaic-large.png");

Pixelate just one rectangle. Crop the area, pixelate it, then put it back at the same coordinates. This example replaces only the 2×2 square at (1, 1) in grid.png; Src replaces the area even if the patch contains transparent pixels.

C#
using OneImage;
 
var image = Image.Load("grid.png").AddAlpha();
var patch = image.Crop(1, 1, 2, 2).Pixelate(2);
image.Composite(patch, x: 1, y: 1,
    alpha: AlphaComposition.Src).Save("patch.png");

Pixelation isn’t a safe way to hide sensitive content.


The short answer

Load an image, call Pixelate(size: 2), then save it. size is the width and height of a block, measured in pixels. The output has the same width and height as the input. OneImage uses one input pixel per block; Pixelate has no averaging mode.

How do I pixelate an image at a different block size?

The best starting size depends on the image’s dimensions and how much detail you want to leave visible. Try 2 for a small sample and increase the size until the squares are visible at the size you’ll display the image. A 4-pixel block spans twice as far in both directions as a 2-pixel block. A size of 1 leaves the image unchanged, which makes it useful as the off setting for a block-size control.

The grid starts at the top left. In each block OneImage samples block start + size / 2 on both axes, using integer division. For a 2×2 block that’s the lower-right pixel of the four. In the sample, output positions (0,0) and (1,0) both get the color from (1,1); (2,0) instead gets the color from (3,1). If the image dimensions aren’t multiples of the block size, OneImage still fills the right and bottom strips without adding pixels. When a sample coordinate would run past an edge, it uses the last pixel along that axis.

What’s the difference between a pixelated image and a blurred image?

A mosaic repeats one exact sample over a square area and leaves a hard boundary between adjacent blocks. A blur uses surrounding pixels, so a sharp boundary tends to spread over neighboring positions rather than becoming a grid of squares. Use pixelation when you want the squares to show, or blur when you want to soften detail while keeping transitions smooth.

Since OneImage doesn’t average the block, a single bright pixel can color an entire square if it lands on the sample point. The same bright pixel might vanish from the mosaic if it falls anywhere else. That makes the effect a poor choice when you need to represent the average color of each area. It’s also not a way to create a smaller canvas: for fewer output pixels, resize instead.

All oneimage recipes