PDF stage 4.9: axial & radial shadings (types 2/3)

Render axial (type 2) and radial (type 3) shadings as SVG gradients, both
via the `sh` operator and via `/PatternType 2` shading patterns selected by
`scn`.

- `pdf_shading.{hpp,cpp}`: `parse_shading` resolves a `/Shading` dictionary,
  pre-sampling its tint `/Function` across `/Domain` into 32 sRGB colour stops
  (no function evaluator needed at render time). Types other than 2/3 and
  malformed shadings return null; `/Extend`, `/Background` and `/BBox` are
  parsed.
- Parser: `parse_resources` now builds the `/Shading` and `/Pattern` resource
  tables (after `/ColorSpace`, so named colour spaces resolve). A shading
  pattern resolves its `/Shading`; a tiling pattern is recognized (rendered in
  4.10). `GraphicsState::Color` carries the selected `/Pattern` name.
- Extractor: `scn` records the pattern name; `paint_path` resolves a shading
  pattern to `PathElement::fill_shading` + the pattern `/Matrix`; the `sh`
  operator emits a `ShadingElement` flooding the current clip.
- HTML: a `GradientRegistry` emits `<linearGradient>`/`<radialGradient>` defs
  with `gradientUnits="userSpaceOnUse"`; a shading-pattern fill paints the path
  through `fill="url(#…)"`, and `sh` paints a clipped `<rect>`. `/Extend` is
  approximated by SVG's `pad` spread.

Tests: shading parsing (axial/radial, domain/extend, background, unsupported
type, short coords, bad function) and extractor wiring (shading-pattern fill,
unknown pattern, `sh` element, unknown shading).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: andiwand

CMakeLists.txt

@@ -200,6 +200,7 @@ set(ODR_SOURCE_FILES
         "src/odr/internal/pdf/pdf_object.cpp"
         "src/odr/internal/pdf/pdf_object_parser.cpp"
         "src/odr/internal/pdf/pdf_page_extractor.cpp"
+        "src/odr/internal/pdf/pdf_shading.cpp"
 
         "src/odr/internal/font/cff_builder.cpp"
         "src/odr/internal/font/cff_font.cpp"

src/odr/internal/html/pdf_file.cpp

@@ -79,6 +79,18 @@ std::string device_color_to_css(const pdf::GraphicsState::Color &color) {
   return std::move(s).str();
 }
 
+/// Convert an sRGB triple in [0, 1] (a shading colour stop) to a CSS
+/// `rgb(...)`.
+std::string rgb_to_css(const std::array<double, 3> &rgb) {
+  const auto to255 = [](const double v) {
+    return static_cast<int>(std::lround(std::clamp(v, 0.0, 1.0) * 255.0));
+  };
+  std::ostringstream s;
+  s << "rgb(" << to255(rgb[0]) << ',' << to255(rgb[1]) << ',' << to255(rgb[2])
+    << ')';
+  return std::move(s).str();
+}
+
 /// Build an SVG `d` attribute from a path's subpaths, each point mapped through
 /// `to_box` (PDF user space -> the page box, y-down). Lines become `L`, cubic
 /// Béziers `C`, and an explicitly closed subpath ends with `Z`.
@@ -117,10 +129,12 @@ std::string svg_path_d(const std::vector<pdf::Subpath> &subpaths,
 /// stroke carries width (CTM-scaled in user space), caps, joins, miter limit
 /// and the dash pattern. A zero stroke width renders as a thin hairline.
 /// `clip_id`, when non-empty, references a `<clipPath>` installed via
-/// `clip-path`.
+/// `clip-path`. `gradient_id`, when non-empty, fills the path with that
+/// gradient (a shading pattern) instead of `fill_color`.
 std::string svg_path_fragment(const pdf::PathElement &path,
                               const util::math::Transform2D &to_box,
-                              const std::string &clip_id) {
+                              const std::string &clip_id,
+                              const std::string &gradient_id) {
   if ((!path.fill && !path.stroke) || path.subpaths.empty()) {
     return {};
   }
@@ -131,7 +145,11 @@ std::string svg_path_fragment(const pdf::PathElement &path,
   }
 
   if (path.fill) {
-    f << " fill=\"" << device_color_to_css(path.fill_color) << '"';
+    if (!gradient_id.empty()) {
+      f << " fill=\"url(#" << gradient_id << ")\"";
+    } else {
+      f << " fill=\"" << device_color_to_css(path.fill_color) << '"';
+    }
     if (path.even_odd) {
       f << " fill-rule=\"evenodd\"";
     }
@@ -253,6 +271,87 @@ class ClipRegistry {
   std::ostringstream m_defs;
 };
 
+/// Registers a page's shadings (axial/radial) as `<linearGradient>`/
+/// `<radialGradient>` defs, deduplicating by shading and placement. The
+/// shading's pre-sampled colour stops become `<stop>`s; `gradientTransform`
+/// (shading space -> page box) places the gradient in the page's user space, so
+/// referencing elements use `gradientUnits="userSpaceOnUse"`. PDF `/Extend` is
+/// approximated by SVG's default `pad` spread (the end stops extend outward).
+/// Ids are namespaced per page (`g<page>_<n>`).
+class GradientRegistry {
+public:
+  explicit GradientRegistry(std::uint32_t page) : m_page{page} {}
+
+  /// The gradient id to reference via `fill="url(#id)"` for `shading` placed by
+  /// `m` (shading space -> page box). Empty for an unrepresentable shading.
+  std::string register_gradient(const pdf::Shading &shading,
+                                const util::math::Transform2D &m) {
+    if ((shading.type != 2 && shading.type != 3) || shading.stops.empty()) {
+      return {};
+    }
+    std::ostringstream sig;
+    sig << shading.type << ':' << static_cast<const void *>(&shading) << ':'
+        << m.a << ',' << m.b << ',' << m.c << ',' << m.d << ',' << m.e << ','
+        << m.f;
+    const auto [it, inserted] = m_id_by_signature.try_emplace(sig.str());
+    if (!inserted) {
+      return it->second;
+    }
+    it->second = "g" + std::to_string(m_page) + "_" + std::to_string(++m_count);
+    const std::string &id = it->second;
+
+    const std::array<double, 6> &c = shading.coords;
+    if (shading.type == 2) {
+      m_defs << "<linearGradient id=\"" << id << "\" x1=\"" << c[0]
+             << "\" y1=\"" << c[1] << "\" x2=\"" << c[2] << "\" y2=\"" << c[3]
+             << '"';
+    } else {
+      // Radial: the outer circle (x1,y1,r1) is SVG's (cx,cy,r); the inner
+      // circle (x0,y0,r0) is the focal point and radius (fr is SVG2).
+      m_defs << "<radialGradient id=\"" << id << "\" cx=\"" << c[3]
+             << "\" cy=\"" << c[4] << "\" r=\"" << c[5] << "\" fx=\"" << c[0]
+             << "\" fy=\"" << c[1] << "\" fr=\"" << c[2] << '"';
+    }
+    m_defs << " gradientUnits=\"userSpaceOnUse\" gradientTransform=\"matrix("
+           << m.a << ',' << m.b << ',' << m.c << ',' << m.d << ','
+           << round2(m.e) << ',' << round2(m.f) << ")\">";
+    for (const pdf::GradientStop &stop : shading.stops) {
+      m_defs << "<stop offset=\"" << round2(stop.offset) << "\" stop-color=\""
+             << rgb_to_css(stop.rgb) << "\"/>";
+    }
+    m_defs << (shading.type == 2 ? "</linearGradient>" : "</radialGradient>");
+    return id;
+  }
+
+  [[nodiscard]] std::string defs() const { return m_defs.str(); }
+
+private:
+  std::uint32_t m_page;
+  std::uint32_t m_count{0};
+  std::unordered_map<std::string, std::string> m_id_by_signature;
+  std::ostringstream m_defs;
+};
+
+/// Serialize an `sh` shading flood to an SVG `<rect>` covering the page box,
+/// filled with `gradient_id` and bounded by `clip_id` (the clip in force at
+/// `sh` time). Returns "" when the shading produced no gradient. The rect spans
+/// the whole page; the clip (and the gradient's own extent) bound the paint.
+std::string svg_shading_fragment(const std::string &gradient_id,
+                                 const std::string &clip_id, double width,
+                                 double height) {
+  if (gradient_id.empty()) {
+    return {};
+  }
+  std::ostringstream f;
+  f << "<rect x=\"0\" y=\"0\" width=\"" << round2(width) << "\" height=\""
+    << round2(height) << "\" fill=\"url(#" << gradient_id << ")\"";
+  if (!clip_id.empty()) {
+    f << " clip-path=\"url(#" << clip_id << ")\"";
+  }
+  f << "/>";
+  return std::move(f).str();
+}
+
 /// Deduplicates CSS declarations into atomic, single-property classes. PDF text
 /// emits one absolutely-positioned span per glyph run, and the same font sizes,
 /// offsets and spacings recur across the (potentially millions of) spans.
@@ -575,14 +674,41 @@ class HtmlServiceImpl final : public HtmlService {
           util::math::Transform2D::scaling_translation(1, -1, 0, height);
 
       ClipRegistry clips(static_cast<std::uint32_t>(pages_out.size()));
+      GradientRegistry gradients(static_cast<std::uint32_t>(pages_out.size()));
 
       for (const pdf::PageElement &element :
            pdf::extract_page(stream, *page->resources, *m_logger)) {
         // A painted path: serialize its subpaths to an SVG `<path>` fragment in
-        // the page viewBox (fill and/or stroke), under any active clip.
+        // the page viewBox (fill and/or stroke), under any active clip. A
+        // shading-pattern fill is painted through a gradient instead of a
+        // colour.
         if (const auto *path = std::get_if<pdf::PathElement>(&element)) {
           const std::string clip_id = clips.register_clip(path->clip, to_box);
-          std::string fragment = svg_path_fragment(*path, to_box, clip_id);
+          std::string gradient_id;
+          if (path->fill_shading != nullptr) {
+            gradient_id = gradients.register_gradient(
+                *path->fill_shading, path->shading_transform * to_box);
+          }
+          std::string fragment =
+              svg_path_fragment(*path, to_box, clip_id, gradient_id);
+          if (!fragment.empty()) {
+            page_out.items.push_back(PathOut{std::move(fragment)});
+          }
+          continue;
+        }
+
+        // An `sh` shading flood: a `<rect>` over the page box filled with the
+        // shading's gradient, bounded by the clip in force at `sh` time.
+        if (const auto *shading = std::get_if<pdf::ShadingElement>(&element)) {
+          if (shading->shading == nullptr) {
+            continue;
+          }
+          const std::string clip_id =
+              clips.register_clip(shading->clip, to_box);
+          const std::string gradient_id = gradients.register_gradient(
+              *shading->shading, shading->transform * to_box);
+          std::string fragment =
+              svg_shading_fragment(gradient_id, clip_id, width, height);
           if (!fragment.empty()) {
             page_out.items.push_back(PathOut{std::move(fragment)});
           }
@@ -788,7 +914,8 @@ class HtmlServiceImpl final : public HtmlService {
         }
       }
 
-      page_out.clip_defs = clips.defs();
+      // Clip-path and gradient defs share the page's hidden `<svg><defs>`.
+      page_out.clip_defs = clips.defs() + gradients.defs();
     }
 
     // Post-pass: every page has been scanned, so the per-font used-scalar sets
@@ -934,10 +1061,11 @@ class HtmlServiceImpl final : public HtmlService {
     for (const PageOut &page : pages_out) {
       out.write_element_begin("div",
                               HtmlElementOptions().set_class(page.classes));
-      // Clip-path defs for this page, in a hidden zero-size `<svg>`. They are
-      // referenced by id from the page's path fragments; `clipPathUnits`
-      // defaults to `userSpaceOnUse`, so the geometry is read in the user space
-      // of the referencing element (the page viewBox), not this `<svg>`.
+      // Clip-path and gradient defs for this page, in a hidden zero-size
+      // `<svg>`. They are referenced by id from the page's fragments;
+      // `clipPathUnits`/`gradientUnits` are `userSpaceOnUse`, so the geometry
+      // is read in the user space of the referencing element (the page
+      // viewBox), not this `<svg>`.
       if (!page.clip_defs.empty()) {
         out.write_raw(
             "<svg width=\"0\" height=\"0\" style=\"position:absolute\">"

src/odr/internal/pdf/AGENTS.md

@@ -574,6 +574,15 @@ stage exists to avoid.
   current fill colour; `/SMask` and `/Mask` (stencil + colour-key) composited
   into RGBA on the raster path (a mask on a JPEG base is ignored — decoding the
   JPEG to composite is out of scope).
+- **Shadings & shading patterns** (axial type 2, radial type 3): `parse_shading`
+  pre-samples the tint `/Function` across `/Domain` into 32 sRGB colour stops, so
+  the renderer needs no function evaluator. The `sh` operator floods the current
+  clip (a `ShadingElement` → `<rect>` filled with the gradient); a `/PatternType
+  2` shading pattern selected by `scn` fills a path (`PathElement::fill_shading`
+  + the pattern `/Matrix`). Both emit SVG `<linearGradient>`/`<radialGradient>`
+  with `gradientUnits="userSpaceOnUse"`; `/Extend` is approximated by SVG's `pad`
+  spread. Mesh/function shadings (types 1, 4–7) and tiling patterns
+  (`/PatternType 1`) are still future stages.
 - **SVG residue** — where no 1:1 primitive exists; all at generation time, never
   rasterization: mesh/function shadings (types 1, 4–7) → tessellate into small
   flat polygons (pdf.js's approach); color spaces

src/odr/internal/pdf/pdf_document_element.hpp

@@ -3,6 +3,7 @@
 #include <odr/internal/pdf/pdf_cmap.hpp>
 #include <odr/internal/pdf/pdf_encoding.hpp>
 #include <odr/internal/pdf/pdf_object.hpp>
+#include <odr/internal/pdf/pdf_shading.hpp>
 #include <odr/internal/util/math_util.hpp>
 
 #include <array>
@@ -28,6 +29,7 @@ struct Annotation;
 struct Resources;
 struct Font;
 struct XObject;
+struct Pattern;
 struct ColorSpaceDef;
 
 struct Element {
@@ -95,6 +97,13 @@ struct Resources final : Element {
   /// referenced by `BDC`. Each value is the resolved property-list dictionary
   /// `Object`; used to recover `/ActualText` for a `BDC /Tag /Name` sequence.
   std::unordered_map<std::string, Object> properties;
+  /// The `/Shading` subdictionary (ISO 32000-1 8.7.4.3): named shadings painted
+  /// by the `sh` operator. Resolved eagerly (the tint function sampled into
+  /// colour stops) so extraction needs no parser handle.
+  std::unordered_map<std::string, std::shared_ptr<Shading>> shading;
+  /// The `/Pattern` subdictionary (ISO 32000-1 8.7.3.3): named tiling/shading
+  /// patterns selected as a colour by `scn`/`SCN` in a `/Pattern` colour space.
+  std::unordered_map<std::string, Pattern *> pattern;
 };
 
 /// An external object referenced by `Do` and listed in a resource dictionary's
@@ -145,6 +154,27 @@ struct XObject final : Element {
   std::vector<double> stencil_decode; ///< `/Decode`, empty = default `[0 1]`
 };
 
+/// A pattern listed in a resource dictionary's `/Pattern` subdictionary
+/// (ISO 32000-1 8.7.3), selected as a colour by `scn`/`SCN` in a `/Pattern`
+/// colour space. Shading patterns (`/PatternType 2`) paint a gradient through
+/// the path; tiling patterns (`/PatternType 1`) repeat a content-stream cell.
+struct Pattern final : Element {
+  enum class Type {
+    unknown,
+    tiling,  ///< `/PatternType 1`
+    shading, ///< `/PatternType 2`
+  };
+  Type type{Type::unknown};
+
+  /// `/Matrix` mapping pattern space to the default coordinate system of the
+  /// pattern's parent content stream (8.7.3.1); default identity.
+  util::math::Transform2D matrix;
+
+  /// Shading pattern (`/PatternType 2`): the shading painted through the path,
+  /// pre-resolved (its tint function sampled into stops). Null otherwise.
+  std::shared_ptr<Shading> shading;
+};
+
 /// A non-owning view over a string of PDF character codes, splitting it into
 /// fixed-width (`Font::code_byte_width()`) big-endian codes on iteration. Holds
 /// only a `string_view`, so it must not outlive the underlying bytes; iterate

src/odr/internal/pdf/pdf_document_parser.cpp

@@ -759,6 +759,79 @@ XObject *parse_x_object(State &state, const ObjectReference &reference) {
   return x_object;
 }
 
+/// A `ColorSpaceContext` over the parser, resolving a base/alternate space
+/// named by name against the (being-built) `/ColorSpace` table of `resources`.
+ColorSpaceContext make_color_space_context(DocumentParser &parser,
+                                           const Resources *resources) {
+  ColorSpaceContext context;
+  context.resolve = [&parser](const Object &object) {
+    return parser.resolve_object_copy(object);
+  };
+  context.load_stream = [&parser](const Object &object) {
+    return object.is_reference()
+               ? parser.read_decoded_stream(object.as_reference())
+               : std::string{};
+  };
+  context.named =
+      [resources](const std::string &name) -> std::shared_ptr<ColorSpaceDef> {
+    const auto it = resources->color_space.find(name);
+    return it != resources->color_space.end() ? it->second : nullptr;
+  };
+  return context;
+}
+
+/// Parse a `/Shading` dictionary into a resolved `Shading` (its tint function
+/// sampled into colour stops). `resources` supplies named colour spaces.
+std::shared_ptr<Shading> parse_shading_resource(State &state,
+                                                const Object &object,
+                                                const Resources *resources) {
+  DocumentParser &parser = state.parser();
+  ShadingContext context;
+  context.resolve = [&parser](const Object &o) {
+    return parser.resolve_object_copy(o);
+  };
+  context.load_stream = [&parser](const Object &o) {
+    return o.is_reference() ? parser.read_decoded_stream(o.as_reference())
+                            : std::string{};
+  };
+  return parse_shading(object, context,
+                       make_color_space_context(parser, resources));
+}
+
+/// Parse a `/Pattern` entry. A shading pattern (`/PatternType 2`) resolves its
+/// `/Shading`; a tiling pattern (`/PatternType 1`) is recognized here and its
+/// content rendered in a later stage. `/Matrix` is taken either way.
+Pattern *parse_pattern(State &state, const ObjectReference &reference,
+                       const Resources *resources) {
+  DocumentParser &parser = state.parser();
+  Document &document = state.document();
+
+  auto *pattern = document.create_element<Pattern>();
+  IndirectObject object = parser.read_object(reference);
+  if (!object.object.is_dictionary()) {
+    return pattern;
+  }
+  const Dictionary &dictionary = object.object.as_dictionary();
+  pattern->object_reference = reference;
+  pattern->object = Object(dictionary);
+
+  if (dictionary.has_value("Matrix")) {
+    pattern->matrix = parse_matrix(parser, dictionary["Matrix"]);
+  }
+  const auto pattern_type = static_cast<std::int32_t>(
+      parser.resolve_object_copy(dictionary.get("PatternType"))
+          .as_integer_opt()
+          .value_or(0));
+  if (pattern_type == 2) {
+    pattern->type = Pattern::Type::shading;
+    pattern->shading =
+        parse_shading_resource(state, dictionary.get("Shading"), resources);
+  } else if (pattern_type == 1) {
+    pattern->type = Pattern::Type::tiling;
+  }
+  return pattern;
+}
+
 Resources *parse_resources(State &state, const Object &object) {
   DocumentParser &parser = state.parser();
   Document &document = state.document();
@@ -820,6 +893,29 @@ Resources *parse_resources(State &state, const Object &object) {
     }
   }
 
+  // Shadings and patterns are parsed after `/ColorSpace` so a named colour
+  // space they reference is already in `resources->color_space`.
+  if (dictionary.has_value("Shading")) {
+    const Dictionary shading_table =
+        parser.resolve_object_copy(dictionary["Shading"]).as_dictionary();
+    for (const auto &[key, value] : shading_table) {
+      if (auto shading = parse_shading_resource(state, value, resources)) {
+        resources->shading[key] = std::move(shading);
+      }
+    }
+  }
+
+  if (dictionary.has_value("Pattern")) {
+    const Dictionary pattern_table =
+        parser.resolve_object_copy(dictionary["Pattern"]).as_dictionary();
+    for (const auto &[key, value] : pattern_table) {
+      if (value.is_reference()) {
+        resources->pattern[key] =
+            parse_pattern(state, value.as_reference(), resources);
+      }
+    }
+  }
+
   if (dictionary.has_key("Properties") && !dictionary["Properties"].is_null()) {
     // Named property lists for `BDC`; resolved eagerly so text extraction can
     // recover `/ActualText` without a parser handle (cf. form XObjects).