Make output coordinates consistent with standard coordinate systems (SVG coordinates)

Author: digi-deity

README.md

@@ -52,7 +52,7 @@ column = TextColumn(
 )
 
 # Get bounding boxes for rendering
-text, x, dx, y, dy = column.to_bounding_boxes()
+text, x, dx, x_origin, y, dy, y_origin = column.to_bounding_boxes()
 ```
 
 ## Usage Examples
@@ -106,7 +106,7 @@ multi_column = MultiColumn(
 )
 
 # Get bounding boxes with column information
-text, x, dx, y, dy, column_id = multi_column.to_bounding_boxes(
+text, x, dx, x_origin, y, dy, y_origin, column_id = multi_column.to_bounding_boxes(
     max_lines_per_column=20,
     line_spacing=1.2
 )
@@ -141,7 +141,7 @@ multi_column = MultiColumn(
 )
 
 # Get positioned text for the layout
-text, x, dx, y, dy, page = layout.to_bounding_boxes(multi_column)
+text, x, dx, x_origin, y, dy, y_origin, page = layout.to_bounding_boxes(multi_column)
 ```
 
 ### SVG Rendering
@@ -150,8 +150,8 @@ text, x, dx, y, dy, page = layout.to_bounding_boxes(multi_column)
 # Generate SVG output
 svg_content = font_measure.render_svg(
     text=text,
-    x=x,
-    y=y,
+    x_origin=x_origin,
+    y_origin=y_origin,
     fontsize=12,
     canvas_width=600,
     canvas_height=800
@@ -162,6 +162,8 @@ with open("output.svg", "w") as f:
     f.write(svg_content)
 ```
 
+**Note on Coordinate System**: TextShape uses the SVG/HTML coordinate system where the origin (0, 0) is at the top-left corner, and the y-axis increases downward. All coordinates returned by `to_bounding_boxes()` follow this convention.
+
 ### Line breaking with hyphenation
 
 ```python
@@ -260,7 +262,7 @@ column = TextColumn(fragments, column_width=widths, fontsize=12)
 Control spacing between lines:
 
 ```python
-text, x, dx, y, dy = column.to_bounding_boxes(line_spacing=1.5)
+text, x, dx, x_origin, y, dy, y_origin = column.to_bounding_boxes(line_spacing=1.5)
 ```
 
 ## Performance Tips

tests/test_layout.py

@@ -8,7 +8,11 @@
 from textshape.layout import Layout
 
 
-def test_multi_column():
+def test_max_lines_per_column():
+    """Test the calculation of maximum lines per column based on page height and font size. We don't move "columns" here,
+    but we will color what would have been a separate column. This also shows that 'newlines' should be ignored if they
+    occur on column boundaries.
+    """
     text = '\t' + '\n\n\t'.join(TEXTS)
 
     fontsize = 12
@@ -19,9 +23,9 @@ def test_multi_column():
     fragments = f(text)
     column = MultiColumn(fragments, column_width=width, fontsize=fontsize, justify=True)
 
-    text, x, dx, y, dy, c = column.to_bounding_boxes(max_lines_per_column=3, reset_y=False)
+    text, x, dx, x_orig, y, dy, y_orig, c = column.to_bounding_boxes(max_lines_per_column=3, reset_y=False)
 
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=width)
+    svg = fm.render_svg(text, x_orig, y_orig, fontsize=fontsize, canvas_width=width)
 
     boundaries = re.compile(r"\t|\b[^\s]")
     separators = np.array([x.span()[0] for x in boundaries.finditer(text)], dtype=int)
@@ -75,18 +79,26 @@ def test_layout():
     fragments = f(text)
     column = MultiColumn(fragments, column_width=layout.column_widths, fontsize=fontsize, justify=True)
 
-    text, x, dx, y, dy, p = layout.to_bounding_boxes(column)
-    y = y - p_height * p  # Adjust y to start from the top of the page
+    text, _, dx, x_orig, _, dy, y_orig, p = layout.to_bounding_boxes(column)
+    y_orig = y_orig + p_height * p  # Adjust y to start from the top of the page
 
     # Only keep values for the first page
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=p_width, canvas_height=(p[-1]+1) * p_height)
+    svg = fm.render_svg(text, x_orig, y_orig, fontsize=fontsize, canvas_width=p_width, canvas_height=(p[-1]+1) * p_height)
 
     def draw_rect(x, y, dx, dy, color="red"):
         return f'<rect width="{dx:.2f}" height="{dy:.2f}" x="{x:.2f}" y="{y:.2f}" style="stroke:{color}"/>'
 
+    # Draw a boundary line between pages
     rects = [
-        draw_rect(margin, -z*p_height, p_width - 2*margin, 1, "black") for z in range(1,p.max() + 1)
+        draw_rect(margin, z*p_height, p_width - 2*margin, 1, "black") for z in range(1,p.max() + 1)
     ]
+
+    # Draw a boundary line for the page margins
+    rects += [
+        draw_rect(margin, p_height * p + margin, p_width - 2*margin, p_height - 2*margin, "blue")
+        for p in range(0, p[-1] + 1)
+    ]
+
     rects = "\n".join(rects)
     rects = f'<g style="stroke-width:1;" fill-opacity="0">\n{rects}\n</g>\n</svg>'
 

tests/test_textwrap.py

@@ -145,9 +145,9 @@ def test_oneliner():
     f = TextFragmenter(measure=fm, splitter=dummy_splitter)
     fragments = f(text)
     column = TextColumn(fragments, column_width=width, fontsize=fontsize)
-    text, x, dx, y, dy = column.to_bounding_boxes()
+    text, _, dx, x_origin, _, dy, y_origin = column.to_bounding_boxes()
 
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=width)
+    svg = fm.render_svg(text, x_origin, y_origin, fontsize=fontsize, canvas_width=width)
     with open(DIR / "text-oneliner.svg", "w") as f:
         f.write(svg)
 
@@ -162,8 +162,8 @@ def test_wrap_font():
     fragments = f(text)
     column = TextColumn(fragments, column_width=width, fontsize=fontsize, justify=False)
 
-    text, x, dx, y, dy = column.to_bounding_boxes()
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=width)
+    text, _, dx, x_origin, _, dy, y_origin = column.to_bounding_boxes()
+    svg = fm.render_svg(text, x_origin, y_origin, fontsize=fontsize, canvas_width=width)
     with open(DIR / "text.svg", "w") as f:
         f.write(svg)
 
@@ -179,8 +179,8 @@ def test_wrap_font_justified():
     fragments = f(text)
     column = TextColumn(fragments, column_width=width, fontsize=fontsize, justify=True)
 
-    text, x, dx, y, dy = column.to_bounding_boxes()
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=width)
+    text, _, dx, x_origin, _, dy, y_origin = column.to_bounding_boxes()
+    svg = fm.render_svg(text, x_origin, y_origin, fontsize=fontsize, canvas_width=width)
     with open(DIR / "text-justified.svg", "w") as f:
         f.write(svg)
 
@@ -195,8 +195,8 @@ def test_heterogeneous_widths():
     fragments = f(text)
     column = TextColumn(fragments, column_width=width, fontsize=fontsize, justify=True)
 
-    text, x, dx, y, dy = column.to_bounding_boxes()
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=46 * fontsize)
+    text, _, dx, x_origin, _, dy, y_origin = column.to_bounding_boxes()
+    svg = fm.render_svg(text, x_origin, y_origin, fontsize=fontsize, canvas_width=46 * fontsize)
     with open(DIR / "text-heterogeneous.svg", "w") as f:
         f.write(svg)
 
@@ -211,8 +211,8 @@ def test_wrap_force_newline_and_tabs():
     fragments = f(text)
     column = TextColumn(fragments, column_width=width, fontsize=fontsize, justify=True)
 
-    text, x, dx, y, dy = column.to_bounding_boxes()
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=width)
+    text, _, dx, x_origin, _, dy, y_origin = column.to_bounding_boxes()
+    svg = fm.render_svg(text, x_origin, y_origin, fontsize=fontsize, canvas_width=width)
     with open(DIR / "text-force-newline-and-tabs.svg", "w") as f:
         f.write(svg)
 
@@ -232,8 +232,8 @@ def test_wrap_font_selection():
     fragments = f(text)
     column = TextColumn(fragments, column_width=width, fontsize=fontsize, justify=True)
 
-    text, x, dx, y, dy = column.to_bounding_boxes(line_spacing=1.2)
-    svg = fm.render_svg(text, x, y, fontsize=fontsize, canvas_width=width)
+    text, x, dx, x_origin, y, dy, y_origin = column.to_bounding_boxes(line_spacing=1.2)
+    svg = fm.render_svg(text, x_origin, y_origin, fontsize=fontsize, canvas_width=width)
 
     boundaries = re.compile(r"\t|\b[^\s]")
     separators = np.array([x.span()[0] for x in boundaries.finditer(text)], dtype=int)

textshape/layout.py

@@ -85,7 +85,7 @@ def column_xy(self) -> tuple[np.ndarray, np.ndarray]:
         """
 
         x = self.page_left_margin + np.pad(np.cumsum(self.column_widths[:-1] + self.column_spacing), (1, 0))
-        y = np.full_like(x, -self.page_top_margin)
+        y = np.full_like(x, self.page_top_margin)
 
         return x, y
 
@@ -101,23 +101,27 @@ def to_bounding_boxes(
 
         line_height = multi_column.fragments.measure.line_gap * multi_column.fontsize * line_spacing
         max_lines = self.max_lines_per_column(line_height)
-        text, x, dx, y, dy, c = multi_column.to_bounding_boxes(
+        text, x, dx, x_orig, y, dy, y_orig, c = multi_column.to_bounding_boxes(
             max_lines_per_column=max_lines,
             line_spacing=line_spacing
         )
 
         x_move, y_move = self.column_xy()
 
-        x = x + x_move[c % self.columns]
-        y = y + y_move[c % self.columns]
+        x += x_move[c % self.columns]
+        x_orig += x_move[c % self.columns]
+        y += y_move[c % self.columns]
+        y_orig += y_move[c % self.columns]
 
         p = c // self.columns
 
         return (
             text,
             x,
             dx,
+            x_orig,
             y,
             dy,
+            y_orig,
             p, # page index
         )

textshape/shape.py

@@ -75,8 +75,8 @@ def character_widths(
     def render_svg(
         self,
         text: str,
-        x: FloatVector,
-        y: FloatVector,
+        x_origin: FloatVector,
+        y_origin: FloatVector,
         fontsize: float,
         canvas_width: float,
         canvas_height: Optional[float] = None,
@@ -90,14 +90,11 @@ def render_svg(
         vhb = self.vhb
 
         s = fontsize / self.em
-        x = x / s
-        y = y / s
 
         font_extents = vhb.hbfont.get_font_extents("ltr")
         line_gap = (
             font_extents.line_gap or font_extents.ascender - font_extents.descender
         ) * s
-        y -= font_extents.descender
 
         x_cursor = 0
         y_cursor = 0
@@ -113,8 +110,8 @@ def render_svg(
             cluster = info.cluster
 
             if cluster > prev_cluster:
-                x_cursor = x[cluster]
-                y_cursor = y[cluster]
+                x_cursor = x_origin[cluster]
+                y_cursor = y_origin[cluster]
             else:
                 # Something interesting with clustering has happened. Advance according to harfbuzz suggestion.
                 x_cursor += prev_x_advance
@@ -136,33 +133,32 @@ def render_svg(
 
         # Add a empty border and rescale
         x_min = 0
-        y_max = 0
+        y_min = 0
         x_max = canvas_width
         if canvas_height is not None:
-            y_min = -canvas_height
+            y_max = canvas_height
         else:
-            y_min = (y.min() + font_extents.descender) * s
+            y_max = y_origin.max() - font_extents.descender * s
 
-        x_min = x_min - line_gap
-        y_min = y_min - line_gap
-        x_max = x_max + line_gap
-        y_max = y_max + line_gap
+        x_min = x_min - 10
+        y_min = y_min - 10
+        x_max = x_max + 10
+        y_max = y_max + 10
 
         svg = [
-            f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="{x_min} {y_min} {x_max - x_min} {y_max - y_min}" transform="matrix(1 0 0 -1 0 0)">',
+            f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="{x_min} {y_min} {x_max - x_min} {y_max - y_min}">',
             f'<rect x="{x_min}" y="{y_min}" width="{x_max - x_min}" height="{y_max - y_min}" fill="#BBBBBB"/>',
-            f'<rect x="{x_min + line_gap}" y="{y_min + line_gap}" width="{x_max - x_min - 2*line_gap}" height="{y_max - y_min - 2*line_gap}" fill="#FFFFFF"/>',
+            f'<rect x="{x_min + 10}" y="{y_min + 10}" width="{x_max - x_min - 2*10}" height="{y_max - y_min - 2*10}" fill="#FFFFFF"/>',
             "<defs>",
             *defs.values(),
             "</defs>",
-            f'<g transform="scale({s}, {s})">',
             *paths,
-            "</g>",
             "</svg>",
             "",
         ]
 
-        return "\n".join(svg)
+        svg = "\n".join(svg)
+        return svg.replace('<use', f'<use transform="scale({s}, {-s})"')
 
 
 def monospace_measure(s: str) -> FloatVector:

textshape/text.py

@@ -120,15 +120,21 @@ def _convert_and_scale(
         dy: FloatVector,
         *args,
     ) -> CharInfoVectors:
-        """Convert the text to a string and scale the coordinates by the fontsize."""
+        """Convert the text to a string and scale the coordinates by the fontsize.
+
+        Additionally add the x_orig and y_orig coordinates as the glyph origin coordinates, which are needed
+        for correct placement of glyphs.
+        """
         text = self._array_to_text(text_vector)
         fontsize = self.fontsize
         return (
             text,
             x * fontsize,
             dx * fontsize,
-            y * fontsize,
+            x * fontsize,  # x_orig is the right edge of the character box, which is the origin for glyph placement
+            (y - self.fragments.measure.ascender) * fontsize,
             dy * fontsize,
+            y * fontsize,
             *args,
         )
 
@@ -232,8 +238,8 @@ def calc_y(
 
         line_gap = self.fragments.measure.line_gap
         y = np.zeros_like(widths)
-        y[0] = -line_gap
-        y[linebreaks] -= line_gap * line_spacing
+        y[0] = self.fragments.measure.ascender
+        y[linebreaks] = line_gap * line_spacing
         y = y.cumsum()
         dy = np.full_like(y, line_gap)
         return dy, y
@@ -320,10 +326,10 @@ def to_bounding_boxes(
         # Reset y-coordinates for each column
         if reset_y:
             splits = np.pad(linebreaks[split_mask], (1, 0))
-            y_offset = np.repeat(y[splits], np.diff(splits, append=len(y)))
-            y = y - y_offset - self.fragments.measure.line_gap
+            y_offset = np.repeat(y[splits], np.diff(splits, append=len(y))) - y[0]
+            y -= y_offset
 
-        # Drop trailing empty lines from each column
+        # Drop trailing empty line characters from columns
         drop_mask = np.ones(len(text), dtype=bool)
         drop_mask[linebreaks[_drop_mask]] = False
         text = text[drop_mask]

textshape/types.py

@@ -12,8 +12,11 @@
 
 CharInfoVectors = tuple[
     str,  # text
+    FloatVector,  # x_origin
+    FloatVector,  # y_origin
     FloatVector,  # x
-    FloatVector,  # y
     FloatVector,  # dx (width)
-    FloatVector,  # dy (height)
+    FloatVector,  # y
+    FloatVector,  # dy (height),
+    ...
 ]