Class InkRaster

Namespace

Egami

Assembly

Egami.dll

A printed page as plates: one plane per ink of an InkSet (a disabled spot has none) plus one alpha plane, each 8 or 16 bits. A plane holds the ink as it prints over paper, 0 for none to the depth's maximum for full ink: drawing translucently leaves less ink, so the planes are premultiplied by the alpha plane, and a plate is ready to print as it is. A new raster is blank: no ink, alpha 0.

public sealed class InkRaster : IDisposable

Inheritance

object

InkRaster

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// A page as plates: CMYK and the spot, 8 bits each, plus alpha. Rows are written in place; a plate is also a gray raster.
using InkRaster page = new(inks, 200, 100, InkDepth.Unorm8);
page.Plate("PANTONE 186 C")!.Row8(10).Fill(255);              // a full-tint line of the spot
page.Alpha.Row8(10).Fill(255);
using Raster<Gray8> spot = page.Plate("PANTONE 186 C")!.AsRaster<Gray8>();   // no copy: 0 = no ink, 255 = full ink

Remarks

Planar storage lets a plate come out as a Raster<TPixel> of Gray8 or Gray16 without copying (AsRaster<TPixel>()), and lets blend modes run one plane at a time. An A4 page at 300 dpi with CMYK and two spots takes 61 MB at 8 bits. Not thread-safe, like Raster.

Constructors

InkRaster(InkSet, int, int, InkDepth, EgamiContext?)

Creates a blank ink raster.

public InkRaster(InkSet inks, int width, int height, InkDepth depth = InkDepth.Unorm8, EgamiContext? context = null)

Parameters

inks InkSet

The inks, fixed for the raster's life.

width int

The width in pixels, at least 1.

height int

The height in pixels, at least 1.

depth InkDepth

The bits per plane.

context EgamiContext

The context to allocate from and whose SafetyLimits apply, or null for Default.

Exceptions

ArgumentNullException

inks is null.

ArgumentOutOfRangeException

width or height is less than 1, or depth is not defined.

LimitExceededException

The size breaks MaxWidth, MaxHeight or MaxPixels, or the planes together break MaxTotalBytes.

Properties

Alpha

Gets the alpha plane: 0 where nothing was drawn to the maximum where the page is covered.

public InkPlate Alpha { get; }

Property Value

InkPlate

Context

Gets the context the raster allocated from.

public EgamiContext Context { get; }

Property Value

EgamiContext

Depth

Gets the bits per plane.

public InkDepth Depth { get; }

Property Value

InkDepth

Height

Gets the height in pixels.

public int Height { get; }

Property Value

int

Inks

Gets the inks.

public InkSet Inks { get; }

Property Value

InkSet

Plates

Gets the plates, one per ink in the set's order, without disabled spots.

public IReadOnlyList<InkPlate> Plates { get; }

Property Value

IReadOnlyList<InkPlate>

Width

Gets the width in pixels.

public int Width { get; }

Property Value

int

Methods

Dispose()

Returns the planes' memory to the context's memory source. Plate rasters taken from it stop working.

public void Dispose()

Load(Stream, ColorProfile?, EgamiContext?)

Loads a separated TIFF (PhotometricInterpretation 5) as an ink raster: 8 or 16-bit strips, chunky or planar, uncompressed, LZW, Deflate or PackBits. The inks are those of the file's embedded CMYK or n-colour profile (else profile, else FOGRA39), plus a spot, without appearance, for each ink it names that the profile lacks; planes are matched by name. Without an alpha extra sample the page counts as covered (alpha at its maximum).

public static InkRaster Load(Stream stream, ColorProfile? profile = null, EgamiContext? context = null)

Parameters

stream Stream

The stream to read, from its position.

profile ColorProfile

The output profile when the file has none, or null for FOGRA39.

context EgamiContext

The context to allocate from and whose limits apply, or null for Default.

Returns

InkRaster

The raster. The caller must dispose it.

Exceptions

UnsupportedFormatException

The file is not a separated TIFF of a kind read here.

CorruptDataException

The file is damaged.

Load(string, ColorProfile?, EgamiContext?)

Loads a separated TIFF (PhotometricInterpretation 5) as an ink raster: 8 or 16-bit strips, chunky or planar, uncompressed, LZW, Deflate or PackBits. The inks are those of the file's embedded CMYK or n-colour profile (else profile, else FOGRA39), plus a spot, without appearance, for each ink it names that the profile lacks; planes are matched by name. Without an alpha extra sample the page counts as covered (alpha at its maximum).

public static InkRaster Load(string path, ColorProfile? profile = null, EgamiContext? context = null)

Parameters

path string

The file to read.

profile ColorProfile

The output profile when the file has none, or null for FOGRA39.

context EgamiContext

The context to allocate from and whose limits apply, or null for Default.

Returns

InkRaster

The raster. The caller must dispose it.

Exceptions

UnsupportedFormatException

The file is not a separated TIFF of a kind read here.

CorruptDataException

The file is damaged.

MeasureCoverage(float)

Measures the ink: the largest total of the printing inks (process and spots; technical inks such as varnish are not counted) on one pixel, where it is, the share of pixels over limit, and each plate's mean coverage.

public InkCoverage MeasureCoverage(float limit = 3)

Parameters

limit float

The total ink limit, as a fraction: 3.0 for 300%, FOGRA39's.

Returns

InkCoverage

The figures.

Examples

// How the plates look on screen, and whether they print within the press's total ink limit.
using Raster<Rgba8> proof = page.Proof<Rgba8>(new ProofOptions { SimulatePaper = true });
InkCoverage coverage = page.MeasureCoverage(limit: 3.0f);
bool tooMuchInk = coverage.MaxTotal > coverage.Limit;      // where: coverage.MaxAt; how often: coverage.ShareOver

Exceptions

ArgumentOutOfRangeException

limit is negative or not finite.

ObjectDisposedException

The raster has been disposed.

Plate(string)

Returns the plate of the ink named name (ordinal), or null when the raster has none.

public InkPlate? Plate(string name)

Parameters

name string

The ink's name.

Returns

InkPlate

The plate, or null.

Proof<TPixel>(ProofOptions?)

Returns how the plates print, on screen: each spot's appearance at full tint, as process tints scaled by the spot's tint, adds to the process inks (capped at full ink, as Ghostscript's and MuPDF's overprint simulation do), and the result goes through the ink set's profile to Target. Technical inks and spots without an appearance do not show; unprinted paper is paper. The plates hold ink as printed, so the proof is opaque.

public Raster<TPixel> Proof<TPixel>(ProofOptions? options = null) where TPixel : unmanaged, IPixelType<TPixel>

Parameters

options ProofOptions

The target encoding and paper, or null for Default.

Returns

Raster<TPixel>

The proof. The caller must dispose it.

Type Parameters

TPixel

The proof's pixel type.

Examples

// How the plates look on screen, and whether they print within the press's total ink limit.
using Raster<Rgba8> proof = page.Proof<Rgba8>(new ProofOptions { SimulatePaper = true });
InkCoverage coverage = page.MeasureCoverage(limit: 3.0f);
bool tooMuchInk = coverage.MaxTotal > coverage.Limit;      // where: coverage.MaxAt; how often: coverage.ShareOver

Exceptions

ObjectDisposedException

The raster has been disposed.

Save(Stream, InkTiffOptions?)

Saves the raster as one separated TIFF: a sample per plate (InkSet 1 for plain CMYK, else 2 with the ink names), stored plane by plane, and the output profile embedded; the alpha plane too when IncludeAlpha says so. libtiff and RIPs read it. Spot appearances and kinds are not kept: TIFF has no place for them.

public void Save(Stream stream, InkTiffOptions? options = null)

Parameters

stream Stream

The stream to write to, at its position.

options InkTiffOptions

The compression and whether to keep alpha, or null for the defaults.

Examples

// One separated TIFF with every plate and the ink names, Deflate by default; it loads back plate for plate.
page.Save(file, new InkTiffOptions { Compression = Egami.Formats.Tiff.TiffCompression.Lzw });
file.Position = 0;
using InkRaster loaded = InkRaster.Load(file);

// One separated TIFF with every plate and the ink names, Deflate by default; it loads back plate for plate.
page.Save(file, new InkTiffOptions { Compression = Egami.Formats.Tiff.TiffCompression.Lzw });
file.Position = 0;
using InkRaster loaded = InkRaster.Load(file);

Exceptions

ObjectDisposedException

The raster has been disposed.

Save(string, InkTiffOptions?)

Saves the raster as one separated TIFF: a sample per plate (InkSet 1 for plain CMYK, else 2 with the ink names), stored plane by plane, and the output profile embedded; the alpha plane too when IncludeAlpha says so. libtiff and RIPs read it. Spot appearances and kinds are not kept: TIFF has no place for them.

public void Save(string path, InkTiffOptions? options = null)

Parameters

path string

The file to write.

options InkTiffOptions

The compression and whether to keep alpha, or null for the defaults.

Examples

// One separated TIFF with every plate and the ink names, Deflate by default; it loads back plate for plate.
page.Save(file, new InkTiffOptions { Compression = Egami.Formats.Tiff.TiffCompression.Lzw });
file.Position = 0;
using InkRaster loaded = InkRaster.Load(file);

Exceptions

ObjectDisposedException

The raster has been disposed.