Class CcittFax

Namespace

Egami.Formats.Ccitt

Assembly

Egami.dll

Raw CCITT fax coding as a PDF filter: Group 3 and Group 4 data (ITU-T T.4 and T.6) with PDF's CCITTFaxDecode parameters, byte-aligned Group 4 included, which a TIFF wrapper cannot express. Decode(ReadOnlySpan<byte>, CcittFaxParameters, out int, EgamiContext?) reads it and Encode(ReadOnlySpan<byte>, CcittFaxParameters) writes Group 4 and one-dimensional Group 3. To load the data as an image instead, use CcittFormat.

public static class CcittFax

Inheritance

object

CcittFax

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// A PDF image with /Filter /CCITTFaxDecode: its DecodeParms become the parameters, and the result is the filter's
// output, packed rows with black 0 and white 1, ready for the image's /Decode array and color space.
CcittFaxParameters parameters = new() { K = -1, EncodedByteAlign = true, Columns = 301, Rows = 48 };
byte[] rows = CcittFax.Decode(stream, parameters, out int rowCount);

Methods

Decode(ReadOnlySpan<byte>, CcittFaxParameters, out int, EgamiContext?)

Decodes CCITT fax data to packed rows, as PDF's CCITTFaxDecode filter gives them: one bit a pixel, most significant bit first, each row padded to whole bytes with 0 bits, black 0 and white 1 unless BlackIs1.

public static byte[] Decode(ReadOnlySpan<byte> data, CcittFaxParameters parameters, out int rows, EgamiContext? context = null)

Parameters

data ReadOnlySpan<byte>

The coded data, as the stream holds it after the filters before CCITTFaxDecode.

parameters CcittFaxParameters

The stream's DecodeParms.

rows int

The number of rows returned: Rows when it is above 0, else the rows decoded.

context EgamiContext

The context whose safety limits and diagnostics apply, or null for Default.

Returns

byte[]

The rows, (Columns + 7) / 8 bytes each.

Examples

// A PDF image with /Filter /CCITTFaxDecode: its DecodeParms become the parameters, and the result is the filter's
// output, packed rows with black 0 and white 1, ready for the image's /Decode array and color space.
CcittFaxParameters parameters = new() { K = -1, EncodedByteAlign = true, Columns = 301, Rows = 48 };
byte[] rows = CcittFax.Decode(stream, parameters, out int rowCount);

Remarks

A damaged row ends decoding (after DamagedRowsBeforeError skipped rows, when it applies): the rows before it are kept, the rest are white, and a warning goes to the context's Diagnostics. Data that ends before Rows rows also warns.

Exceptions

ArgumentNullException

parameters is null.

ArgumentOutOfRangeException

A parameter is outside what it can mean, such as Columns below 1.

CorruptDataException

Not one row decodes.

LimitExceededException

The image breaks a safety limit.

Encode(ReadOnlySpan<byte>, CcittFaxParameters)

Encodes packed rows as CCITT fax data, the inverse of Decode(ReadOnlySpan<byte>, CcittFaxParameters, out int, EgamiContext?): one bit a pixel, most significant bit first, each row padded to whole bytes, black 0 and white 1 unless BlackIs1. The parameters that describe the result are the ones a PDF's DecodeParms then carries.

public static byte[] Encode(ReadOnlySpan<byte> rows, CcittFaxParameters parameters)

Parameters

rows ReadOnlySpan<byte>

The packed rows, (Columns + 7) / 8 bytes each; padding bits are ignored.

parameters CcittFaxParameters

The coding to write: K, EndOfLine, EndOfBlock, Columns, Rows and BlackIs1 are used.

Returns

byte[]

The coded data.

Examples

// A bi-level scan as a PDF image with /Filter /CCITTFaxDecode: pack its rows (0 black, 1 white), then write Group 4.
int rowBytes = (scan.Width + 7) / 8;
byte[] rows = new byte[rowBytes * scan.Height];
for (int y = 0; y < scan.Height; y++)
{
    Span<Gray8> row = scan.Row(y);
    for (int x = 0; x < scan.Width; x++)
    {
        if (row[x].L >= 128)
        {
            rows[(y * rowBytes) + (x >> 3)] |= (byte)(0x80 >> (x & 7));
        }
    }
}

// These parameters are the image's DecodeParms: << /K -1 /Columns 301 /Rows 48 >>.
CcittFaxParameters parameters = new() { K = -1, Columns = scan.Width, Rows = scan.Height };
byte[] g4 = CcittFax.Encode(rows, parameters);

Remarks

K below 0 writes Group 4 (ITU-T T.6), the smallest coding for scanned text; 0 writes one-dimensional Group 3 (modified Huffman rows). EndOfLine puts an EOL before each Group 3 row, and EndOfBlock ends the data with RTC or EOFB. The row count is Rows when it is above 0, else every whole row of rows.

Exceptions

ArgumentNullException

parameters is null.

ArgumentOutOfRangeException

A parameter is outside what it can mean, or rows holds fewer rows than Rows.

NotSupportedException

K above 0 (mixed Group 3) or EncodedByteAlign is asked for: neither is written.