feat: JPEG 2000 codec and PDF JPXDecode support

.cspell.yaml

@@ -14,6 +14,64 @@ language: en
 
 # Project-specific technical terms and tool names
 words:
+  - bitplanes
+  - bitstream
+  - Cdef
+  - codestreams
+  - coef
+  - Colr
+  - CPRL
+  - csiz
+  - dequantization
+  - Dmax
+  - Dmin
+  - dplanes
+  - EBCOT
+  - fplane
+  - INITDEC
+  - INITENC
+  - Ippm
+  - Irrev
+  - isot
+  - Lblock
+  - LRCP
+  - lsot
+  - luts
+  - Mallat
+  - mant
+  - Memberwise
+  - NLPS
+  - NMPS
+  - Nppm
+  - Osiz
+  - Pclr
+  - Pcoc
+  - PCRL
+  - Prec
+  - Psot
+  - pterm
+  - Renorm
+  - RLCP
+  - RPCL
+  - rsiz
+  - scoc
+  - scod
+  - segsym
+  - signedness
+  - smask
+  - ssiz
+  - subband
+  - Sycc
+  - Termall
+  - Tsiz
+  - vcausal
+  - vsum
+  - xmap
+  - xmaps
+  - Xsiz
+  - ymaps
+  - ysiz
+  - Zppm
   - Aabb
   - functiontype
   - Poppler

.reviewmark.yaml

@@ -254,6 +254,27 @@ reviews:
       - "test/DemaConsulting.CanvasNet.Tests/Codecs/GifCodecTests.cs"  # unit tests
       - "test/DemaConsulting.CanvasNet.Tests/Codecs/GifFixtureTests.cs"  # fixture conformance tests
 
+  # CanvasNet-Codecs-Jpeg2000Codec Review (one per unit)
+  - id: CanvasNet-Codecs-Jpeg2000Codec
+    title: Review that CanvasNet Codecs Jpeg2000Codec Implementation is Correct
+    context:
+      - "docs/design/canvas-net.md"
+      - "docs/reqstream/canvas-net.yaml"
+      - "docs/design/canvas-net/codecs.md"
+      - "docs/reqstream/canvas-net/codecs.yaml"
+    paths:
+      - "docs/reqstream/canvas-net/codecs/jpeg2000-codec.yaml"    # unit requirements
+      - "docs/design/canvas-net/codecs/jpeg2000-codec.md"        # unit design
+      - "docs/verification/canvas-net/codecs/jpeg2000-codec.md"  # unit verification
+      - "src/DemaConsulting.CanvasNet/Codecs/Jpeg2000Codec.cs"       # unit source (public API entry point)
+      - "src/DemaConsulting.CanvasNet/Codecs/Jpeg2000Image.cs"       # unit source (public decoded-image result type)
+      - "src/DemaConsulting.CanvasNet/Codecs/Jpeg2000ColorSpace.cs"  # unit source (public color-space enum)
+      - "src/DemaConsulting.CanvasNet/Codecs/Jpeg2000/**/*.cs"       # unit source (partial-class implementation files)
+      - "src/DemaConsulting.CanvasNet/Codecs/ImageInfo.cs"           # shared header-only probe result type
+      - "src/DemaConsulting.CanvasNet/Codecs/NamespaceDoc.cs"        # Codecs namespace documentation
+      - "test/DemaConsulting.CanvasNet.Tests/Codecs/Jpeg2000CodecTests.cs"      # unit tests
+      - "test/DemaConsulting.CanvasNet.Tests/Codecs/Jpeg2000TestEncoder*.cs"    # test-only JPEG 2000 encoder
+
   # CanvasNet-Geometry Review (one per subsystem)
   - id: CanvasNet-Geometry
     title: Review that CanvasNet Geometry Subsystem Implementation is Correct
@@ -770,6 +791,7 @@ reviews:
       - "src/DemaConsulting.CanvasNet.Pdf/NamespaceDoc.cs"             # Pdf namespace documentation
       - "test/DemaConsulting.CanvasNet.Pdf.Tests/PdfDocumentTests.cs"  # unit tests
       - "test/DemaConsulting.CanvasNet.Pdf.Tests/PdfDocumentMeshShadingTests.cs"  # mesh shading unit tests
+      - "test/DemaConsulting.CanvasNet.Pdf.Tests/PdfDocumentJpxTests.cs"  # JPXDecode/SMask unit tests
       - "test/DemaConsulting.CanvasNet.Pdf.Tests/PdfSystemIntegrationTests.cs"  # integration tests
       - "test/DemaConsulting.CanvasNet.Pdf.Tests/PdfFixtureTests.cs"   # fixture conformance tests
 

README.md

@@ -31,6 +31,7 @@ image operations using `Span<T>`, and supports independent-copy cropping for loa
 - 🖨️ **TIFF Codec** - Load/save 8-bit RGB/RGBA/Grayscale TIFF files
 - 🗜️ **JPEG Codec** - Load baseline/progressive; save baseline JPEG
 - 🎞️ **GIF Codec** - Decode-only load of first GIF frame; `GetInfo` reports the true frame count
+- 🖼️ **JPEG 2000 Codec** - Decode-only load of JP2 files and raw codestreams (Decode also exposes color space and alpha)
 - 📐 **SVG Codec** - Rasterize a common SVG subset to a surface (`DemaConsulting.CanvasNet.Svg`)
 - 📄 **PDF Document** - Open, inspect, and rasterize PDF pages with font substitution (`DemaConsulting.CanvasNet.Pdf`)
 - 📊 **Chart Rendering** - Build and paint Bar/Column/Line/Area/Pie/Doughnut charts (`DemaConsulting.CanvasNet.Charts`)
@@ -88,7 +89,7 @@ PngCodec.Save(surface, "surface.png");
 using var reloaded = PngCodec.Load("surface.png");
 ```
 
-Open a PDF and render a page (BMP/TIFF/JPEG/GIF/SVG codecs, header-only probing, and
+Open a PDF and render a page (BMP/TIFF/JPEG/GIF/JPEG 2000/SVG codecs, header-only probing, and
 feature-detection all follow the same pattern):
 
 ```csharp

docs/design/canvas-net-pdf.md

@@ -47,9 +47,9 @@ size — but every filled/stroked path painted in solid opaque black, since no c
 implemented yet. Phase 3 added real device color (`g`/`G`/`rg`/`RG`/`k`/`K`/`cs`/
 `CS`/`sc`/`SC`/`scn`/`SCN`), a generalized `/Filter`/`/DecodeParms` stream-decoding pipeline
 (`FlateDecode` plus PNG/TIFF predictor reversal), and image XObjects (`Do`: `DCTDecode` via the
-`CanvasNet` system's `Codecs.JpegCodec`, or raw `DeviceGray`/`DeviceRGB`/`DeviceCMYK` 8-bit
-samples, composited through the current transformation matrix). Phase 4 added real text/font
-rendering: `BT`/`ET`/`Tc`/`Tw`/`Tz`/`TL`/`Tf`/`Tr`/`Ts`/`Td`/`TD`/`Tm`/`T*`/`Tj`/`'`/`"`/
+`CanvasNet` system's `Codecs.JpegCodec`, `JPXDecode` via `Codecs.Jpeg2000Codec`, or raw
+`DeviceGray`/`DeviceRGB`/`DeviceCMYK` 8-bit samples, composited through the current transformation matrix).
+Phase 4 added real text/font rendering: `BT`/`ET`/`Tc`/`Tw`/`Tz`/`TL`/`Tf`/`Tr`/`Ts`/`Td`/`TD`/`Tm`/`T*`/`Tj`/`'`/`"`/
 `TJ` resolve a simple `/Subtype /TrueType` font from the current page's `/Resources/Font`
 dictionary (requiring an embedded `/FontDescriptor/FontFile2`, loaded via the `CanvasNet`
 system's `Fonts.TrueTypeFont`), map each shown byte through its `/WinAnsiEncoding`/
@@ -106,8 +106,8 @@ Form XObject's `/BBox` is never used to clip its content and its `/Group` (trans
 entry is never consulted, though the Form itself renders; `/ShadingType` values outside `2`-`7`
 and `/FunctionType 4` (PostScript calculator) functions fail closed; the `sh` operator and general
 path clipping (`W`/`W*`) are supported; no
-`/SMask`/alpha compositing or transparency groups (every decoded image is treated as fully
-opaque); no `JPXDecode` filter decoding (fails closed; `CCITTFaxDecode` - Group 4 (T.6 MMR) only -
+`/Mask`/`/Matte` image masks or transparency groups (an explicit `/SMask` and JPEG 2000
+alpha are applied); `JPXDecode` is decoded (`CCITTFaxDecode` - Group 4 (T.6 MMR) only -
 is supported); `/Separation`/`/DeviceN`/`/CalGray`/`/Lab` color spaces remain unsupported and fail
 closed; and an encrypted document using any security handler, crypt-filter method, `/V`/`/R`
 combination other than the ones listed above, or whose correct password is not supplied, fails
@@ -335,7 +335,7 @@ crypt filter), `pdf-encrypted-r-{revision}`,
 non-empty one is genuinely required), `pdf-encrypted-incorrect-password`,
 `pdf-encrypted-password-non-ascii` (an R2-R4 password outside ASCII 0-127),
 `pdf-colorspace-{name}` (`Separation`/`DeviceN`/`CalGray`/`Lab`), `pdf-colorspace-Pattern`,
-`pdf-colorspace-ICCBased`, `pdf-filter-{name}` (`JPXDecode` and any other unrecognized filter),
+`pdf-colorspace-ICCBased`, `pdf-filter-{name}` (any unrecognized filter),
 `pdf-tiff-predictor-bitdepth-{n}`, `pdf-image-bitdepth-{n}`, `pdf-pattern-not-declared`,
 `pdf-pattern-type-{n}`, `pdf-pattern-tile-too-large`, `pdf-shading-type-{n}`,
 `pdf-shading-colorspace-{family}`, `pdf-functiontype-{n}`, `pdf-function-multiinput`,

docs/design/canvas-net-pdf/pdf-document.md

@@ -34,8 +34,8 @@ filter pipeline, image XObjects (Phase 3), and, as of Phase 4, real embedded-Tru
 rendering: `g`/`G`/`rg`/`RG`/`k`/`K`/`cs`/`CS`/`sc`/`SC`/`scn`/`SCN` set the actual fill/stroke
 color a path paints with; a generalized `/Filter`/`/DecodeParms` pipeline (`FlateDecode` plus
 PNG/TIFF predictor reversal) decodes any stream, not only a page's own `/Contents`; `Do` decodes
-and composites a `/Subtype /Image` XObject (`DCTDecode` via `Codecs.JpegCodec`, or raw
-`DeviceGray`/`DeviceRGB`/`DeviceCMYK` 8-bit samples) through the current transformation matrix;
+and composites a `/Subtype /Image` XObject (`DCTDecode` via `Codecs.JpegCodec`, `JPXDecode` via
+`Codecs.Jpeg2000Codec`, or raw `DeviceGray`/`DeviceRGB`/`DeviceCMYK` 8-bit samples) through the current transformation matrix;
 and `BT`/`ET`/`Tc`/`Tw`/`Tz`/`TL`/`Tf`/`Tr`/`Ts`/`Td`/`TD`/`Tm`/`T*`/`Tj`/`'`/`"`/`TJ` resolve a
 simple (non-composite) TrueType font declared in the current page's `/Resources/Font`
 dictionary, map each shown byte through that font's `/Encoding` to a Unicode codepoint, and paint
@@ -94,10 +94,10 @@ glyph under a clip mode fails closed); and no additional stream filters were add
 no transparency groups; shading/tiling pattern fills were added (`/ShadingType 2`/`3`,
 `/PatternType 1`/`2` — see _`/Pattern` Color Space (Shading and Tiling Patterns)_ below, reusing
 the `/FunctionType 0` sampled-function evaluator originally landed as Phase 1 groundwork,
-alongside new `/FunctionType 2`/`3` support), no `JPX` filter decoding (fails closed;
-`LZWDecode`/`ASCII85Decode`/`ASCIIHexDecode`/`RunLengthDecode` are supported as of Phase 7, and
-`CCITTFaxDecode` - Group 4 (T.6 MMR) only - is supported as of Phase 15, see below), and no
-`/SMask`/alpha compositing (every decoded image is treated as fully opaque) — these
+alongside new `/FunctionType 2`/`3` support), `JPXDecode` is decoded (see Image XObjects below; `LZWDecode`/`ASCII85Decode`/
+`ASCIIHexDecode`/`RunLengthDecode` are supported as of Phase 7, and
+`CCITTFaxDecode` - Group 4 (T.6 MMR) only - is supported as of Phase 15, see below), and
+`/Mask`/`/Matte` image masks remain unsupported (an explicit `/SMask` soft mask is applied) — these
 remain out of scope for this phase and are silently skipped (any other undefined keyword) or
 explicitly rejected (unsupported color spaces/filters/fonts/encodings/render modes), per the
 operator/exception taxonomy documented below; a later phase is expected to add transparency
@@ -698,8 +698,9 @@ its own distinguishable `Feature` token.
   `Codecs/Png/PngCodec.Filtering.cs`'s `DefilterRow`/`Sub`/`Up`/`Average`/`Paeth`/Paeth-predictor
   algorithm, since those methods are `private` in a different assembly and cannot be reused
   directly).   Any other filter name (including `DCTDecode`/`CCITTFaxDecode`, which `PdfDocument.Images.cs`
-  always detects and bypasses before calling this pipeline; and `JPXDecode`/`JBIG2Decode`/
-  `Crypt`, which remain out of scope) throws
+  always detects and bypasses before calling this pipeline; `JPXDecode` (handled by the dedicated JPX
+  path described below), and
+  `JBIG2Decode`/`Crypt`, which remain out of scope) throws
   `Codecs.UnsupportedImageFeatureException`; a malformed `/Filter`/`/DecodeParms` shape, an
   unrecognized `/Predictor` value, or malformed bytes for any of the five supported filters
   (missing EOD marker, invalid/out-of-range code or character, truncated run, or an out-of-range
@@ -725,8 +726,26 @@ its own distinguishable `Feature` token.
   `ColorFromComponents`; an `/Indexed` sample is passed through `SamplesToColor` as a raw,
   un-normalized palette index rather than divided by `255.0` like every other color space) and
   `/BitsPerComponent` (`8` only — anything else throws
-  `Codecs.UnsupportedImageFeatureException`); `/SMask`/`/Mask` are never consulted (every decoded
-  image is treated as fully opaque, a documented Phase 3 limitation).
+  `Codecs.UnsupportedImageFeatureException`). A bare `/Filter /JPXDecode` image is detected and
+  dispatched to `DecodeJpxImageXObject`, which decodes the stream via
+  `Codecs.Jpeg2000Codec.Decode(byte[])` (trusting the decoder's dimensions over `/Width`/`/Height`
+  and mapping any `Jpeg2000Codec` failure to the existing `InvalidDataException`/
+  `UnsupportedImageFeatureException` conventions); `JPXDecode` combined with any other filter
+  throws `InvalidDataException`. When `/ColorSpace` is absent the JP2's own color space is used
+  (gray, sRGB, CMYK, or by channel count; five or more channels need an explicit `/ColorSpace`
+  and otherwise throw `UnsupportedImageFeatureException`); when present, `/ColorSpace`
+  (`DeviceGray`/`DeviceRGB`/`DeviceCMYK`, `/Indexed`, `/ICCBased` by component count) overrides it
+  and its component count must equal the decoded color channel count
+  (`InvalidDataException` otherwise); an `/Indexed` override uses the decoded 8-bit samples as
+  indices. An optional `/Decode` array (`DecodeArray`, applied to JPX images only) remaps each
+  8-bit sample; a wrong-length or non-numeric array throws `InvalidDataException`.
+  `/SMaskInData` selects how the codestream's opacity channel is used: `0` ignores it, `1` applies
+  it as straight alpha, `2` un-premultiplies the color and then applies it; other values throw
+  `InvalidDataException`. An explicit `/SMask` image (any filter, including `JPXDecode`; decoded
+  through the same `DecodeImageSamples` path without nested masks) is nearest-neighbor resampled
+  to the base image and its luminance multiplies the base alpha (`ApplySoftMask`), taking
+  precedence over `/SMaskInData`; `/Mask` and `/Matte` are not consulted. Inline images (`BI`) are
+  not supported at all, which satisfies the PDF rule that `JPXDecode` is not permitted inline.
   `CompositeImageOntoSurface` inverts the CTM (a non-invertible/degenerate CTM silently paints
   nothing), computes the device-space bounding box of the transformed unit square, and for every
   destination pixel in that box nearest-neighbor-samples the source image (`row = floor((1 - v) *

docs/design/canvas-net.md

@@ -27,7 +27,9 @@ DEMA Consulting best practices. The system consists of six implemented subsystem
   `JpegCodec` (a common real-world subset of JPEG: baseline/progressive decode with
   4:4:4/4:2:2/4:2:0 support, baseline 4:2:0 encode), and `GifCodec` (decode-only load of a GIF's
   first image frame, including LZW decompression and deinterlacing, plus a `GetInfo` that reports
-  the file's true total frame count without resolving later frames into a `Surface`). See
+  the file's true total frame count without resolving later frames into a `Surface`), and
+  `Jpeg2000Codec` (decode-only JPEG 2000 Part 1 decoder for JP2 files and raw codestreams, also
+  exposing the decoded color space and opacity channel for PDF `/JPXDecode` images). See
   _Codecs Subsystem Design_ (`codecs.md`).
 - **Geometry subsystem** (namespace `DemaConsulting.CanvasNet.Geometry`, folder
   `src/DemaConsulting.CanvasNet/Geometry/`, flat — no further nesting): vector-geometry
@@ -82,9 +84,9 @@ DEMA Consulting best practices. The system consists of six implemented subsystem
 
 The `Codecs` subsystem depends on the `Canvas` subsystem's `Surface` unit (constructing surfaces
 and reading/writing rows via `Surface.GetRowSpanBytes`); the `Canvas` subsystem has no dependency
-on `Codecs` or on any other subsystem. Within the `Codecs` subsystem, its five units are flat and
-mutually independent — none of `BmpCodec`, `PngCodec`, `TiffCodec`, `JpegCodec`, or `GifCodec`
-depends on any other codec. Each codec also exposes a pair of `GetInfo(Stream)`/`GetInfo(string)` overloads
+on `Codecs` or on any other subsystem. Within the `Codecs` subsystem, its six units are flat and
+mutually independent — none of `BmpCodec`, `PngCodec`, `TiffCodec`, `JpegCodec`, `GifCodec`,
+or `Jpeg2000Codec` depends on any other codec. Each codec also exposes a pair of `GetInfo(Stream)`/`GetInfo(string)` overloads
 returning the shared `ImageInfo` record struct (width, height, channel count, and alpha presence)
 without fully decoding pixel data and without enforcing `Surface.MaxDimension` (now a public
 constant, so callers can perform this comparison themselves before ever calling `Load`) — except
@@ -97,7 +99,8 @@ pattern, and _Surface Unit Design_ (`canvas/surface.md`) for `MaxDimension`. See
 _Surface Unit Design_ (`canvas/surface.md`), _BmpCodec Unit Design_
 (`codecs/bmp-codec.md`), _PngCodec Unit Design_ (`codecs/png-codec.md`),
 _TiffCodec Unit Design_ (`codecs/tiff-codec.md`), _JpegCodec Unit Design_
-(`codecs/jpeg-codec.md`), and _GifCodec Unit Design_ (`codecs/gif-codec.md`) for each unit's
+(`codecs/jpeg-codec.md`), _GifCodec Unit Design_ (`codecs/gif-codec.md`), and
+_Jpeg2000Codec Unit Design_ (`codecs/jpeg2000-codec.md`) for each unit's
 internal collaboration.
 
 The `Geometry` subsystem's five units collaborate as follows: `PathBuilder` records raw drawing
@@ -239,6 +242,16 @@ The system exposes the following public API to external consumers:
   `ImageInfo` record struct, additionally reporting the file's true total frame count; unlike
   every other codec's `GetInfo`, this decodes the first frame's LZW-compressed pixel data to
   validate `CanDecode` (but never resolves it into a rendered `Surface`).
+- **Jpeg2000Codec.Load(Stream stream)** / **Jpeg2000Codec.Load(string path)**: Loads a `Surface` from a
+  JPEG 2000 (JP2 or raw codestream) stream or file (decode-only - no save support). Throws
+  `ArgumentNullException` for a null `stream`/`path`, `ArgumentException` for an empty `path`,
+  `FileNotFoundException` for a missing file, `InvalidDataException` for malformed data, and
+  `UnsupportedImageFeatureException` for valid but unsupported JPEG 2000 features.
+- **Jpeg2000Codec.GetInfo(Stream stream)** / **Jpeg2000Codec.GetInfo(string path)**: Returns the shared
+  `ImageInfo` record struct from the container and SIZ header alone, without decoding pixels.
+- **Jpeg2000Codec.Decode(Stream stream)** / **Jpeg2000Codec.Decode(byte[] data)**: Decodes to a
+  `Jpeg2000Image` exposing 8-bit color samples, color space, optional opacity samples and ICC
+  profile.
 - **Rect(float x, float y, float width, float height)**: Constructor; an axis-aligned rectangle in
   position-plus-size form. `Rect.Empty` is a static, publicly readable union-identity sentinel.
 - **Rect.Union(Rect)** / **Rect.Union(Rect, Rect)**: Returns the smallest rectangle enclosing both
@@ -354,6 +367,9 @@ The system exposes the following public API to external consumers:
 | `JpegCodec.Save(...)`                        | Inbound          | Method call                    | `surface` non-null            |
 | `GifCodec.Load(...)`                         | Inbound/Outbound | Method call / `Surface` return | Valid GIF stream or path      |
 | `GifCodec.GetInfo(...)`                      | Inbound/Outbound | Method call / `ImageInfo`      | Valid GIF stream or path      |
+| `Jpeg2000Codec.Load(...)`                    | Inbound/Outbound | Method call / `Surface` return | Valid JPEG 2000 stream/path   |
+| `Jpeg2000Codec.GetInfo(...)`                 | Inbound/Outbound | Method call / `ImageInfo`      | Valid JPEG 2000 stream/path   |
+| `Jpeg2000Codec.Decode(...)`                  | Inbound/Outbound | Method call / `Jpeg2000Image`  | Valid JPEG 2000 stream/bytes  |
 | `Rect.Union(...)`                            | Inbound/Outbound | Method call / `Rect` return    | None                          |
 | `Rect.Intersect(...)`                        | Inbound/Outbound | Method call / `Rect` return    | None                          |
 | `Rect.Transform(Matrix3x2)`                  | Inbound/Outbound | Method call / `Rect` return    | None                          |
@@ -577,6 +593,17 @@ measures (IEC 62304 §5.3.3).
    then scanning, without fully decoding, every subsequent frame's own block structure) without
    ever resolving those later frames into a rendered `Surface`
 
+**JPEG 2000 load path:**
+
+1. **Input**: Method parameter `stream`/`path` (or `data` for `Decode`)
+2. **Validation**: `ArgumentNullException` for null arguments, `ArgumentException` for an empty
+   `path`, `InvalidDataException` for malformed data, `UnsupportedImageFeatureException` for
+   unsupported features
+3. **Processing**: Parses the JP2 boxes (if any) and codestream headers, decodes tier-2 packets and
+   tier-1 code-blocks, applies dequantization, the inverse wavelet and component transforms, and
+   scales samples to 8 bits
+4. **Output**: A new `Surface` (`Load`) or a `Jpeg2000Image` (`Decode`)
+
 **TrueType font load and glyph-query path:**
 
 1. **Input**: A font stream or file path, followed by caller-supplied codepoints or glyph indices