docling-parse 7.5.0__tar.gz → 7.6.0__tar.gz

{docling_parse-7.5.0 → docling_parse-7.6.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [v7.6.0](https://github.com/docling-project/docling-parse/releases/tag/v7.6.0) - 2026-07-06
+
+### Feature
+
+* Working on refactoring the parse for shapes ([#293](https://github.com/docling-project/docling-parse/issues/293)) ([`cbe73a8`](https://github.com/docling-project/docling-parse/commit/cbe73a8cc4fae6da7c9bf23914d9571c1c5cf011))
+
 ## [v7.5.0](https://github.com/docling-project/docling-parse/releases/tag/v7.5.0) - 2026-07-03
 
 ### Feature

{docling_parse-7.5.0 → docling_parse-7.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.5.0
+Version: 7.6.0
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT

{docling_parse-7.5.0 → docling_parse-7.6.0}/app/pybind_parse.cpp

@@ -153,13 +153,41 @@ namespace
     {
       pybind11::dict row;
       row["type"] = instruction_name(pdflib::SHAPE_RENDER_INSTRUCTION);
-      row["x"] = instr.get_x();
-      row["y"] = instr.get_y();
-      row["closing_type"] = static_cast<int>(instr.get_closing_type());
-      row["shape_type"] = static_cast<int>(instr.get_shape_type());
+
+      pybind11::list subpaths;
+      for(const auto& sp : instr.get_subpaths())
+        {
+          pybind11::dict sub;
+          sub["x0"] = sp.get_x0();
+          sub["y0"] = sp.get_y0();
+
+          pybind11::list ops;
+          for(const auto op : sp.get_ops())
+            {
+              ops.append(static_cast<int>(op));
+            }
+          sub["ops"] = ops;
+          sub["px"] = sp.get_px();
+          sub["py"] = sp.get_py();
+
+          sub["closing_type"] = static_cast<int>(sp.get_closing_type());
+          sub["shape_type"] = static_cast<int>(sp.get_shape_type());
+          subpaths.append(sub);
+        }
+      row["subpaths"] = subpaths;
+
+      row["paint_mode"] = static_cast<int>(instr.get_paint_mode());
+      row["fill_rule"] = static_cast<int>(instr.get_fill_rule());
       row["line_width"] = instr.get_line_width();
+      row["line_cap"] = instr.get_line_cap();
+      row["line_join"] = instr.get_line_join();
+      row["miter_limit"] = instr.get_miter_limit();
+      row["dash_array"] = instr.get_dash_array();
+      row["dash_phase"] = instr.get_dash_phase();
       row["rgb_stroking"] = instr.get_rgb_stroking();
       row["rgb_filling"] = instr.get_rgb_filling();
+      row["stroke_alpha"] = instr.get_stroke_alpha();
+      row["fill_alpha"] = instr.get_fill_alpha();
       instructions.append(row);
     }
   };

{docling_parse-7.5.0 → docling_parse-7.6.0}/docling_parse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.5.0
+Version: 7.6.0
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT

{docling_parse-7.5.0 → docling_parse-7.6.0}/docling_parse.egg-info/SOURCES.txt

@@ -516,6 +516,8 @@ src/parse/pdf_decoders/document.h
 src/parse/pdf_decoders/page.h
 src/parse/pdf_decoders/stream.h
 src/parse/pdf_decoders/stream_enums.h
+src/parse/pdf_resources/page_colorspace.h
+src/parse/pdf_resources/page_colorspaces.h
 src/parse/pdf_resources/page_font.h
 src/parse/pdf_resources/page_fonts.h
 src/parse/pdf_resources/page_grph.h
@@ -656,9 +658,11 @@ src/third_party/pdfium_jbig2/core/fxcrt/numerics/safe_math.h
 src/third_party/pdfium_jbig2/core/fxcrt/numerics/safe_math_arm_impl.h
 src/third_party/pdfium_jbig2/core/fxcrt/numerics/safe_math_clang_gcc_impl.h
 src/third_party/pdfium_jbig2/core/fxcrt/numerics/safe_math_shared_impl.h
+tests/README.md
 tests/__init__.py
 tests/conftest.py
 tests/data_utils.py
+tests/rendering_regression.py
 tests/test_embedded_fonts.py
 tests/test_locale_safety.py
 tests/test_parse.py

{docling_parse-7.5.0 → docling_parse-7.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-parse"
-version = "7.5.0"
+version = "7.6.0"
 description = "Simple package to extract text with coordinates from programmatic PDFs"
 license = "MIT"
 keywords = ["docling", "pdf", "parser"]

{docling_parse-7.5.0 → docling_parse-7.6.0}/src/parse/enums.h

@@ -186,6 +186,43 @@ namespace pdflib
     BEZIER,      // cubic Bézier curve (interpolated)
   };
 
+  // How a path-painting operator paints the current path
+  enum shape_paint_mode {
+    SHAPE_PAINT_STROKE,        // S, s
+    SHAPE_PAINT_FILL,          // f, F, f*
+    SHAPE_PAINT_FILL_STROKE,   // B, B*, b, b*
+  };
+
+  enum shape_fill_rule {
+    SHAPE_FILL_NONZERO,        // f, B, b
+    SHAPE_FILL_EVEN_ODD,       // f*, B*, b*
+  };
+
+  // Exact path segment commands (each subpath starts with an implicit
+  // move-to). Kept alongside the flattened polyline so the renderer can
+  // rebuild true curves at device resolution.
+  enum shape_segment_op {
+    SEGMENT_LINE_TO,    // consumes 1 point:  end
+    SEGMENT_CUBIC_TO,   // consumes 3 points: ctrl1, ctrl2, end
+  };
+
+  // Families of PDF colour spaces (8.6) that the SC/SCN/sc/scn operands are
+  // interpreted against once CS/cs has resolved a named /ColorSpace resource.
+  enum color_space_family {
+    COLOR_SPACE_UNKNOWN,
+
+    COLOR_SPACE_GRAY,       // DeviceGray, CalGray, ICCBased /N 1
+    COLOR_SPACE_RGB,        // DeviceRGB, CalRGB, ICCBased /N 3
+    COLOR_SPACE_CMYK,       // DeviceCMYK, ICCBased /N 4
+    COLOR_SPACE_LAB,        // Lab (approximated by its L* component)
+
+    COLOR_SPACE_INDEXED,    // palette lookup into a base space
+    COLOR_SPACE_SEPARATION, // single tint (tint transform not evaluated)
+    COLOR_SPACE_DEVICE_N,   // multiple tints (tint transform not evaluated)
+
+    COLOR_SPACE_PATTERN
+  };
+
 }
 
 #endif

{docling_parse-7.5.0 → docling_parse-7.6.0}/src/parse/page_items/embedded_font_blob.h

@@ -31,6 +31,7 @@ namespace pdflib
                        embedded_font_format format,
                        bool is_cid_font,
                        bool cid_to_gid_identity,
+                       bool uses_builtin_encoding,
                        std::shared_ptr<const std::vector<uint8_t> > bytes);
 
     // Content-derived identity (FNV-1a over the decoded bytes + size).
@@ -52,6 +53,14 @@ namespace pdflib
     // /CIDToGIDMap is /Identity or absent
     bool get_cid_to_gid_identity() const { return cid_to_gid_identity; }
 
+    // True for a simple font that is symbolic (/FontDescriptor /Flags bit 3)
+    // and has no /Encoding override: its PDF character codes address the
+    // font program's builtin cmap directly (PDF 32000-1, 9.6.6.4). Shaping
+    // Unicode text against such a face mis-hits glyphs whenever a codepoint
+    // collides with the font's code range (e.g. U+0020 landing on subset
+    // code 0x20 of a Cairo/LibreOffice subset).
+    bool get_uses_builtin_encoding() const { return uses_builtin_encoding; }
+
     const std::shared_ptr<const std::vector<uint8_t> >& get_bytes() const { return bytes; }
 
     bool has_bytes() const;
@@ -71,6 +80,7 @@ namespace pdflib
 
     bool is_cid_font;
     bool cid_to_gid_identity;
+    bool uses_builtin_encoding;
 
     std::shared_ptr<const std::vector<uint8_t> > bytes;
   };
@@ -83,6 +93,7 @@ namespace pdflib
     format(embedded_font_format::UNKNOWN),
     is_cid_font(false),
     cid_to_gid_identity(false),
+    uses_builtin_encoding(false),
     bytes(nullptr)
   {}
 
@@ -93,6 +104,7 @@ namespace pdflib
                                                 embedded_font_format format_,
                                                 bool is_cid_font_,
                                                 bool cid_to_gid_identity_,
+                                                bool uses_builtin_encoding_,
                                                 std::shared_ptr<const std::vector<uint8_t> > bytes_):
     cache_key(std::move(cache_key_)),
     font_name(std::move(font_name_)),
@@ -101,6 +113,7 @@ namespace pdflib
     format(format_),
     is_cid_font(is_cid_font_),
     cid_to_gid_identity(cid_to_gid_identity_),
+    uses_builtin_encoding(uses_builtin_encoding_),
     bytes(std::move(bytes_))
   {}
 

{docling_parse-7.5.0 → docling_parse-7.6.0}/src/parse/page_items/page_shape.h

@@ -41,6 +41,20 @@ namespace pdflib
 
     void append(double x_, double y_);
 
+    // Dual-track geometry: `append` only extends the flattened polyline
+    // (JSON output, bbox/degeneracy checks); the methods below additionally
+    // record the exact segment structure so the renderer can rebuild true
+    // curves. The subpath start (move-to) is the first plain `append`;
+    // closing edges are expressed via closing_type, not as a segment.
+    void append_line_segment(double x_, double y_);
+    void append_cubic_segment(double x1_, double y1_,
+                              double x2_, double y2_,
+                              double x3_, double y3_);
+
+    const std::vector<shape_segment_op>& get_seg_ops() const { return seg_ops; }
+    const std::vector<double>& get_seg_x() const { return seg_x; }
+    const std::vector<double>& get_seg_y() const { return seg_y; }
+
     size_t size();
 
     std::pair<double, double> front();
@@ -64,10 +78,15 @@ namespace pdflib
 
   private:
 
-    std::vector<int>    i;    
+    std::vector<int>    i;
     std::vector<double> x;
     std::vector<double> y;
 
+    // exact segment structure (not serialized; render-instruction path only)
+    std::vector<shape_segment_op> seg_ops;
+    std::vector<double>           seg_x; // op-consumed points,
+    std::vector<double>           seg_y; // in op order
+
     // graphics state properties
     bool has_graphics_state = false;
 
@@ -206,6 +225,14 @@ namespace pdflib
 	utils::values::rotate_inplace(angle, x.at(l), y.at(l));
 	utils::values::translate_inplace(delta, x.at(l), y.at(l));
       }
+
+    // affine maps transform Bézier control points exactly, so the segment
+    // track follows the same point-wise mapping as the polyline
+    for(size_t l=0; l<seg_x.size(); l++)
+      {
+	utils::values::rotate_inplace(angle, seg_x.at(l), seg_y.at(l));
+	utils::values::translate_inplace(delta, seg_x.at(l), seg_y.at(l));
+      }
   }
   
   void page_item<PAGE_SHAPE>::append(double x_, double y_)
@@ -216,6 +243,37 @@ namespace pdflib
     i.back() += 1;
   }
 
+  void page_item<PAGE_SHAPE>::append_line_segment(double x_, double y_)
+  {
+    // the first point of a subpath is the move-to, not a segment
+    if(not x.empty())
+      {
+        seg_ops.push_back(SEGMENT_LINE_TO);
+        seg_x.push_back(x_);
+        seg_y.push_back(y_);
+      }
+
+    this->append(x_, y_);
+  }
+
+  void page_item<PAGE_SHAPE>::append_cubic_segment(double x1_, double y1_,
+                                                   double x2_, double y2_,
+                                                   double x3_, double y3_)
+  {
+    // records only the exact curve; the caller appends the flattened
+    // samples through `append` (interpolate) to keep the polyline intact
+    seg_ops.push_back(SEGMENT_CUBIC_TO);
+
+    seg_x.push_back(x1_);
+    seg_y.push_back(y1_);
+
+    seg_x.push_back(x2_);
+    seg_y.push_back(y2_);
+
+    seg_x.push_back(x3_);
+    seg_y.push_back(y3_);
+  }
+
   size_t page_item<PAGE_SHAPE>::size()
   {
     return x.size();
@@ -279,22 +337,37 @@ namespace pdflib
         // p 120
         for(int j=0; j<3; j++)
           {
-            //LOG_S(WARNING) << trafo_matrix[0*3+j] << "\t" << trafo_matrix[1*3+j] << "\t" << trafo_matrix[2*3+j];
-
             for(int i=0; i<3; i++)
               {
                 d[j] += u[i]*trafo_matrix[i*3+j];
               }
-
-            //LOG_S(WARNING) << x[0] << "\t" << y[0] << "\t -> \t" << d[0] << "\t" << d[1];
           }
 
         x_.push_back(d[0]);
         y_.push_back(d[1]);
       }
-    
+
     x = x_;
     y = y_;
+
+    // affine maps transform Bézier control points exactly, so the segment
+    // track follows the same point-wise mapping as the polyline
+    for(size_t l=0; l<seg_x.size(); l++)
+      {
+        std::array<double, 3> u = {seg_x[l], seg_y[l], 1.0};
+        std::array<double, 3> d = {0.0, 0.0, 0.0};
+
+        for(int j=0; j<3; j++)
+          {
+            for(int i=0; i<3; i++)
+              {
+                d[j] += u[i]*trafo_matrix[i*3+j];
+              }
+          }
+
+        seg_x[l] = d[0];
+        seg_y[l] = d[1];
+      }
   }
   
 }

{docling_parse-7.5.0 → docling_parse-7.6.0}/src/parse/page_items/render_instructions.h

@@ -52,6 +52,17 @@ namespace pdflib
     bool empty() const { return x.empty() or y.empty(); }
     size_t size() const { return std::min(x.size(), y.size()); }
 
+    // Copy shifted by (dx, dy); used to lift widget appearance-stream
+    // geometry from AP-local into page coordinates.
+    clip_path_instruction translated(double dx, double dy) const
+    {
+      std::vector<double> x_(x), y_(y);
+      for(auto& v : x_) { v += dx; }
+      for(auto& v : y_) { v += dy; }
+      return clip_path_instruction(std::move(x_), std::move(y_),
+                                   closing_type, shape_type);
+    }
+
   private:
     std::vector<double> x;
     std::vector<double> y;
@@ -91,6 +102,17 @@ namespace pdflib
       return rule != CLIP_RULE_NONE and not paths.empty();
     }
 
+    clip_state_instruction translated(double dx, double dy) const
+    {
+      std::vector<clip_path_instruction> paths_;
+      paths_.reserve(paths.size());
+      for(const auto& path : paths)
+        {
+          paths_.push_back(path.translated(dx, dy));
+        }
+      return clip_state_instruction(rule, std::move(paths_));
+    }
+
   private:
     clip_rule rule;
     std::vector<clip_path_instruction> paths;
@@ -227,6 +249,42 @@ namespace pdflib
     void set_glyph_name(std::string glyph_name);
     const std::string& get_glyph_name() const;
 
+    // Fill color of the graphics state at emission time (defaults: opaque
+    // black) and the Tr text rendering mode (3/7 paint no glyphs).
+    void set_fill_color(const std::array<int, 3>& rgb, double alpha);
+    const std::array<int, 3>& get_rgb_filling() const { return rgb_filling_; }
+    double get_fill_alpha() const { return fill_alpha_; }
+
+    void set_rendering_mode(int mode) { rendering_mode_ = mode; }
+    int get_rendering_mode() const { return rendering_mode_; }
+    bool is_invisible() const { return rendering_mode_ == 3 or rendering_mode_ == 7; }
+
+    // Copy shifted by (dx, dy); used to lift widget appearance-stream text
+    // from AP-local into page coordinates. The glyph bbox (g_*) lives in
+    // font units and is copied unshifted.
+    text_instruction translated(double dx, double dy) const
+    {
+      text_instruction copy(text, font_enc, font_key, font_name,
+                            encoding_name, base_font, font_size,
+                            r_x0 + dx, r_y0 + dy,
+                            r_x1 + dx, r_y1 + dy,
+                            r_x2 + dx, r_y2 + dy,
+                            r_x3 + dx, r_y3 + dy,
+                            font_ascent_norm, font_descent_norm,
+                            base_x0 + dx, base_y0 + dy,
+                            has_glyph_bbox_,
+                            g_x0_, g_y0_, g_x1_, g_y1_);
+
+      copy.embedded_font_  = embedded_font_;
+      copy.char_code_      = char_code_;
+      copy.glyph_name_     = glyph_name_;
+      copy.rgb_filling_    = rgb_filling_;
+      copy.fill_alpha_     = fill_alpha_;
+      copy.rendering_mode_ = rendering_mode_;
+
+      return copy;
+    }
+
   private:
 
     const std::string text;
@@ -262,6 +320,10 @@ namespace pdflib
     std::shared_ptr<const embedded_font_blob> embedded_font_;
     int64_t char_code_ = -1;
     std::string glyph_name_;
+
+    std::array<int, 3> rgb_filling_ = {0, 0, 0};
+    double fill_alpha_ = 1.0;
+    int rendering_mode_ = 0;
   };
 
   inline void text_instruction::set_embedded_font(std::shared_ptr<const embedded_font_blob> blob)
@@ -299,6 +361,13 @@ namespace pdflib
     return glyph_name_;
   }
 
+  inline void text_instruction::set_fill_color(const std::array<int, 3>& rgb,
+                                               double alpha)
+  {
+    rgb_filling_ = rgb;
+    fill_alpha_ = alpha;
+  }
+
   class text_widget_instruction
   {
   public:
@@ -424,46 +493,186 @@ namespace pdflib
     const clip_state_instruction clip_state;
   };
 
+  // One subpath of a painted path: an implicit move-to (x0, y0) followed by
+  // a run of segment ops. SEGMENT_LINE_TO consumes one coordinate pair from
+  // px/py, SEGMENT_CUBIC_TO consumes three (ctrl1, ctrl2, end) — mirroring
+  // BLPath's command/vertex-array model, so the renderer can rebuild true
+  // curves instead of flattened polylines.
+  class shape_subpath
+  {
+  public:
+    shape_subpath();
+    shape_subpath(double x0, double y0,
+                  std::vector<shape_segment_op> ops,
+                  std::vector<double> px,
+                  std::vector<double> py,
+                  page_shape_closing_type closing_type,
+                  page_shape_type shape_type);
+
+    double get_x0() const { return x0; }
+    double get_y0() const { return y0; }
+
+    const std::vector<shape_segment_op>& get_ops() const { return ops; }
+    const std::vector<double>& get_px() const { return px; }
+    const std::vector<double>& get_py() const { return py; }
+
+    page_shape_closing_type get_closing_type() const { return closing_type; }
+    page_shape_type         get_shape_type()   const { return shape_type; }
+
+    bool empty() const { return ops.empty(); }
+
+    shape_subpath translated(double dx, double dy) const
+    {
+      std::vector<double> px_(px), py_(py);
+      for(auto& v : px_) { v += dx; }
+      for(auto& v : py_) { v += dy; }
+      return shape_subpath(x0 + dx, y0 + dy, ops,
+                           std::move(px_), std::move(py_),
+                           closing_type, shape_type);
+    }
+
+  private:
+
+    double x0; // subpath start (move-to)
+    double y0;
+
+    std::vector<shape_segment_op> ops;
+    std::vector<double> px; // op-consumed points,
+    std::vector<double> py; // in op order
+
+    page_shape_closing_type closing_type;
+    page_shape_type         shape_type;
+  };
+
+  inline shape_subpath::shape_subpath():
+    x0(0.0),
+    y0(0.0),
+    ops(),
+    px(),
+    py(),
+    closing_type(CLOSING_UNDEFINED),
+    shape_type(SHAPE_UNDEFINED)
+  {}
+
+  inline shape_subpath::shape_subpath(double x0_, double y0_,
+                                      std::vector<shape_segment_op> ops_,
+                                      std::vector<double> px_,
+                                      std::vector<double> py_,
+                                      page_shape_closing_type closing_type_,
+                                      page_shape_type shape_type_):
+    x0(x0_),
+    y0(y0_),
+    ops(std::move(ops_)),
+    px(std::move(px_)),
+    py(std::move(py_)),
+    closing_type(closing_type_),
+    shape_type(shape_type_)
+  {}
+
+  // One path-painting operator (S, s, f, F, f*, B, B*, b, b*): all subpaths
+  // of the painted path plus the graphics-state parameters needed to color
+  // it. Fill rules operate on the whole path, so the subpaths must stay in
+  // one instruction (a rectangle-with-hole is two subpaths of one fill).
   class shape_instruction
   {
   public:
     const static RENDER_INSTRUCTION_NAME instr = SHAPE_RENDER_INSTRUCTION;
 
-    shape_instruction(std::vector<double> x,
-                      std::vector<double> y,
-                      page_shape_closing_type closing_type,
-                      page_shape_type         shape_type,
+    shape_instruction(std::vector<shape_subpath> subpaths,
+                      shape_paint_mode        paint_mode,
+                      shape_fill_rule         fill_rule,
                       double                  line_width,
+                      int                     line_cap,
+                      int                     line_join,
+                      double                  miter_limit,
+                      std::vector<double>     dash_array,
+                      double                  dash_phase,
                       std::array<int, 3>      rgb_stroking,
-                      std::array<int, 3>      rgb_filling):
-      x(std::move(x)),
-      y(std::move(y)),
-      closing_type(closing_type),
-      shape_type(shape_type),
+                      std::array<int, 3>      rgb_filling,
+                      double                  stroke_alpha,
+                      double                  fill_alpha,
+                      clip_state_instruction  clip_state = clip_state_instruction()):
+      subpaths(std::move(subpaths)),
+      paint_mode(paint_mode),
+      fill_rule(fill_rule),
       line_width(line_width),
+      line_cap(line_cap),
+      line_join(line_join),
+      miter_limit(miter_limit),
+      dash_array(std::move(dash_array)),
+      dash_phase(dash_phase),
       rgb_stroking(rgb_stroking),
-      rgb_filling(rgb_filling) {}
+      rgb_filling(rgb_filling),
+      stroke_alpha(stroke_alpha),
+      fill_alpha(fill_alpha),
+      clip_state(std::move(clip_state)) {}
 
-    const std::vector<double>& get_x() const { return x; }
-    const std::vector<double>& get_y() const { return y; }
-    size_t size() const { return x.size(); }
+    const std::vector<shape_subpath>& get_subpaths() const { return subpaths; }
+
+    // total number of points (subpath starts + op-consumed points)
+    size_t size() const
+    {
+      size_t n = 0;
+      for(const auto& sp : subpaths)
+        {
+          n += 1 + sp.get_px().size();
+        }
+      return n;
+    }
 
-    page_shape_closing_type     get_closing_type()  const { return closing_type; }
-    page_shape_type             get_shape_type()    const { return shape_type; }
+    shape_paint_mode            get_paint_mode()    const { return paint_mode; }
+    shape_fill_rule             get_fill_rule()     const { return fill_rule; }
     double                      get_line_width()    const { return line_width; }
+    int                         get_line_cap()      const { return line_cap; }
+    int                         get_line_join()     const { return line_join; }
+    double                      get_miter_limit()   const { return miter_limit; }
+    const std::vector<double>&  get_dash_array()    const { return dash_array; }
+    double                      get_dash_phase()    const { return dash_phase; }
     const std::array<int, 3>&   get_rgb_stroking()  const { return rgb_stroking; }
     const std::array<int, 3>&   get_rgb_filling()   const { return rgb_filling; }
 
+    // ExtGState constant alpha (/CA, /ca); 1.0 = opaque, 0.0 = invisible
+    double get_stroke_alpha() const { return stroke_alpha; }
+    double get_fill_alpha()   const { return fill_alpha; }
+
+    const clip_state_instruction& get_clip_state() const { return clip_state; }
+    bool has_clip_state() const { return clip_state.has_clip(); }
+
+    shape_instruction translated(double dx, double dy) const
+    {
+      std::vector<shape_subpath> subpaths_;
+      subpaths_.reserve(subpaths.size());
+      for(const auto& subpath : subpaths)
+        {
+          subpaths_.push_back(subpath.translated(dx, dy));
+        }
+      return shape_instruction(std::move(subpaths_), paint_mode, fill_rule,
+                               line_width, line_cap, line_join, miter_limit,
+                               dash_array, dash_phase,
+                               rgb_stroking, rgb_filling,
+                               stroke_alpha, fill_alpha,
+                               clip_state.translated(dx, dy));
+    }
+
   private:
 
-    const std::vector<double> x;
-    const std::vector<double> y;
+    const std::vector<shape_subpath> subpaths;
 
-    const page_shape_closing_type closing_type;
-    const page_shape_type         shape_type;
+    const shape_paint_mode        paint_mode;
+    const shape_fill_rule         fill_rule;
     const double                  line_width;
+    const int                     line_cap;
+    const int                     line_join;
+    const double                  miter_limit;
+    const std::vector<double>     dash_array;
+    const double                  dash_phase;
     const std::array<int, 3>      rgb_stroking;
     const std::array<int, 3>      rgb_filling;
+
+    const double                  stroke_alpha;
+    const double                  fill_alpha;
+
+    const clip_state_instruction  clip_state;
   };
 
   class pdf_render_instructions
@@ -488,6 +697,18 @@ namespace pdflib
     void add_bitmap_instruction(bitmap_instruction_type instr);
     void add_shape_instruction(shape_instruction_type instr);
 
+    // Read access for re-emitting instructions of a sub-decode (widget
+    // appearance streams) into the main instruction list.
+    const std::vector<shape_instruction_type>& get_shape_instructions() const
+    {
+      return shape_instructions;
+    }
+
+    const std::vector<text_instruction_type>& get_text_instructions() const
+    {
+      return text_instructions;
+    }
+
     // render method
     template<typename renderer_type>
     void iterate_over_instructions(renderer_type& renderer);