figquilt 0.1.2__tar.gz → 0.1.4__tar.gz

{figquilt-0.1.2 → figquilt-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: figquilt
-Version: 0.1.2
+Version: 0.1.4
 Summary: figquilt is a small, language-agnostic CLI tool that composes multiple figures (PDF/SVG/PNG) into a single publication-ready figure, based on a simple layout file (YAML/JSON). The key function is creating a PDF by composing multiple PDFs and adding subfigure labels and minimal annotations.
 Author: YY Ahn
 Author-email: YY Ahn <yongyeol@gmail.com>
@@ -24,9 +24,16 @@ Description-Content-Type: text/markdown
 
 # figquilt
 
-**Figure quilter**: A CLI tool to compositing multiple figures (PDF, SVG, PNG) into a publication-ready figure layout.
+**Figure quilter**: A declarative CLI tool for compositing multiple figures (PDF, SVG, PNG) into publication-ready layouts.
 
-`figquilt` takes a simple layout file (YAML) describing panels and their positions, composed of various inputs (plots from R/Python, diagrams, photos), and stitches them into a single output file (PDF, SVG) with precise dimension control and automatic labeling.
+`figquilt` takes a simple layout file (YAML) describing panels and their structure, composed of various inputs (plots from R/Python, diagrams, photos), and stitches them into a single output file (PDF, SVG) with automatic labeling and precise dimension control.
+
+## Philosophy
+
+- **Declarative over imperative**: Describe *what* your figure should look like, not *how* to construct it. Layouts are data, not scripts.
+- **Structural composition first**: Prefer high-level layout (rows, columns, ratios) over manual coordinate placement. Let the tool handle positioning.
+- **Fine control when needed**: Override with explicit coordinates and dimensions when precision matters.
+- **Automation-friendly**: Designed to fit into reproducible workflows (Snakemake, Make, CI pipelines). No GUI, no manual steps.
 
 ## Features
 

{figquilt-0.1.2 → figquilt-0.1.4}/README.md

@@ -1,8 +1,15 @@
 # figquilt
 
-**Figure quilter**: A CLI tool to compositing multiple figures (PDF, SVG, PNG) into a publication-ready figure layout.
+**Figure quilter**: A declarative CLI tool for compositing multiple figures (PDF, SVG, PNG) into publication-ready layouts.
 
-`figquilt` takes a simple layout file (YAML) describing panels and their positions, composed of various inputs (plots from R/Python, diagrams, photos), and stitches them into a single output file (PDF, SVG) with precise dimension control and automatic labeling.
+`figquilt` takes a simple layout file (YAML) describing panels and their structure, composed of various inputs (plots from R/Python, diagrams, photos), and stitches them into a single output file (PDF, SVG) with automatic labeling and precise dimension control.
+
+## Philosophy
+
+- **Declarative over imperative**: Describe *what* your figure should look like, not *how* to construct it. Layouts are data, not scripts.
+- **Structural composition first**: Prefer high-level layout (rows, columns, ratios) over manual coordinate placement. Let the tool handle positioning.
+- **Fine control when needed**: Override with explicit coordinates and dimensions when precision matters.
+- **Automation-friendly**: Designed to fit into reproducible workflows (Snakemake, Make, CI pipelines). No GUI, no manual steps.
 
 ## Features
 

{figquilt-0.1.2 → figquilt-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "figquilt"
-version = "0.1.2"
+version = "0.1.4"
 description = "figquilt is a small, language-agnostic CLI tool that composes multiple figures (PDF/SVG/PNG) into a single publication-ready figure, based on a simple layout file (YAML/JSON). The key function is creating a PDF by composing multiple PDFs and adding subfigure labels and minimal annotations."
 readme = "README.md"
 authors = [

{figquilt-0.1.2 → figquilt-0.1.4}/src/figquilt/compose_pdf.py

@@ -1,15 +1,16 @@
 import fitz
 from pathlib import Path
 from .layout import Layout, Panel
-from .units import mm_to_pt
+from .units import mm_to_pt, to_pt
 from .errors import FigQuiltError
 
 
 class PDFComposer:
     def __init__(self, layout: Layout):
         self.layout = layout
-        self.width_pt = mm_to_pt(layout.page.width)
-        self.height_pt = mm_to_pt(layout.page.height)
+        self.units = layout.page.units
+        self.width_pt = to_pt(layout.page.width, self.units)
+        self.height_pt = to_pt(layout.page.height, self.units)
 
     def compose(self, output_path: Path):
         doc = self.build()
@@ -63,9 +64,9 @@ class PDFComposer:
         self, doc: fitz.Document, page: fitz.Page, panel: Panel, index: int
     ):
         # Calculate position and size first
-        x = mm_to_pt(panel.x)
-        y = mm_to_pt(panel.y)
-        w = mm_to_pt(panel.width)
+        x = to_pt(panel.x, self.units)
+        y = to_pt(panel.y, self.units)
+        w = to_pt(panel.width, self.units)
 
         # Determine height from aspect ratio if needed
         # We need to open the source to get aspect ratio
@@ -86,14 +87,27 @@ class PDFComposer:
                 src_page = src_doc[0]
                 src_rect = src_page.rect
 
-            aspect = src_rect.height / src_rect.width
+            src_aspect = src_rect.height / src_rect.width
 
+            # Calculate cell height
             if panel.height is not None:
-                h = mm_to_pt(panel.height)
+                h = to_pt(panel.height, self.units)
             else:
-                h = w * aspect
-
-            rect = fitz.Rect(x, y, x + w, y + h)
+                # No height specified: use source aspect ratio
+                h = w * src_aspect
+
+            # Calculate content rect using fit mode
+            from .units import calculate_fit
+
+            content_w, content_h, offset_x, offset_y = calculate_fit(
+                src_aspect, w, h, panel.fit
+            )
+            rect = fitz.Rect(
+                x + offset_x,
+                y + offset_y,
+                x + offset_x + content_w,
+                y + offset_y + content_h,
+            )
 
             if src_doc.is_pdf:
                 page.show_pdf_page(rect, src_doc, 0)

{figquilt-0.1.2 → figquilt-0.1.4}/src/figquilt/compose_svg.py

@@ -2,7 +2,7 @@ from pathlib import Path
 import base64
 from lxml import etree
 from .layout import Layout, Panel
-from .units import mm_to_pt
+from .units import mm_to_pt, to_pt
 from .errors import FigQuiltError
 import fitz
 
@@ -10,8 +10,9 @@ import fitz
 class SVGComposer:
     def __init__(self, layout: Layout):
         self.layout = layout
-        self.width_pt = mm_to_pt(layout.page.width)
-        self.height_pt = mm_to_pt(layout.page.height)
+        self.units = layout.page.units
+        self.width_pt = to_pt(layout.page.width, self.units)
+        self.height_pt = to_pt(layout.page.height, self.units)
 
     def compose(self, output_path: Path):
         # Create root SVG element
@@ -20,8 +21,10 @@ class SVGComposer:
             "xlink": "http://www.w3.org/1999/xlink",
         }
         root = etree.Element("svg", nsmap=nsmap)
-        root.set("width", f"{self.layout.page.width}mm")
-        root.set("height", f"{self.layout.page.height}mm")
+        # SVG uses "in" for inches, "pt" for points, "mm" for millimeters
+        svg_unit = "in" if self.units == "inches" else self.units
+        root.set("width", f"{self.layout.page.width}{svg_unit}")
+        root.set("height", f"{self.layout.page.height}{svg_unit}")
         root.set("viewBox", f"0 0 {self.width_pt} {self.height_pt}")
         root.set("version", "1.1")
 
@@ -42,9 +45,9 @@ class SVGComposer:
             tree.write(f, pretty_print=True, xml_declaration=True, encoding="utf-8")
 
     def _place_panel(self, root: etree.Element, panel: Panel, index: int):
-        x = mm_to_pt(panel.x)
-        y = mm_to_pt(panel.y)
-        w = mm_to_pt(panel.width)
+        x = to_pt(panel.x, self.units)
+        y = to_pt(panel.y, self.units)
+        w = to_pt(panel.width, self.units)
 
         # Determine content sizing
         # For simplicity in V0, relying on fitz for aspect ratio of all inputs (robust)
@@ -56,30 +59,50 @@ class SVGComposer:
         try:
             src_page = src_doc[0]
             src_rect = src_page.rect
-            aspect = src_rect.height / src_rect.width
+            src_aspect = src_rect.height / src_rect.width
 
             if panel.height is not None:
-                h = mm_to_pt(panel.height)
+                h = to_pt(panel.height, self.units)
             else:
-                h = w * aspect
+                h = w * src_aspect
+
+            # Calculate content dimensions using fit mode
+            from .units import calculate_fit
+
+            content_w, content_h, offset_x, offset_y = calculate_fit(
+                src_aspect, w, h, panel.fit
+            )
 
             # Group for the panel
             g = etree.SubElement(root, "g")
             g.set("transform", f"translate({x}, {y})")
 
+            # For cover mode, add a clip path to crop the overflow
+            if panel.fit == "cover":
+                clip_id = f"clip-{panel.id}"
+                defs = etree.SubElement(g, "defs")
+                clip_path = etree.SubElement(defs, "clipPath")
+                clip_path.set("id", clip_id)
+                clip_rect = etree.SubElement(clip_path, "rect")
+                clip_rect.set("x", "0")
+                clip_rect.set("y", "0")
+                clip_rect.set("width", str(w))
+                clip_rect.set("height", str(h))
+
             # Insert content
             # Check if SVG
             suffix = panel.file.suffix.lower()
             if suffix == ".svg":
                 # Embed SVG by creating an <image> tag with data URI to avoid DOM conflicts
-                # This is safer than merging trees for V0.
-                # Merging trees requires stripping root, handling viewbox/transform matching.
-                # <image> handles scaling automatically.
                 data_uri = self._get_data_uri(panel.file, "image/svg+xml")
                 img = etree.SubElement(g, "image")
-                img.set("width", str(w))
-                img.set("height", str(h))
+                img.set("x", str(offset_x))
+                img.set("y", str(offset_y))
+                img.set("width", str(content_w))
+                img.set("height", str(content_h))
                 img.set("{http://www.w3.org/1999/xlink}href", data_uri)
+                if panel.fit == "cover":
+                    img.set("clip-path", f"url(#{clip_id})")
             else:
                 # PDF or Raster Image
                 # For PDF, we rasterize to PNG (easiest for SVG compatibility without huge libs)
@@ -109,12 +132,16 @@ class SVGComposer:
                     data_uri = self._get_data_uri(data_path, mime)
 
                 img = etree.SubElement(g, "image")
-                img.set("width", str(w))
-                img.set("height", str(h))
+                img.set("x", str(offset_x))
+                img.set("y", str(offset_y))
+                img.set("width", str(content_w))
+                img.set("height", str(content_h))
                 img.set("{http://www.w3.org/1999/xlink}href", data_uri)
+                if panel.fit == "cover":
+                    img.set("clip-path", f"url(#{clip_id})")
 
-            # Label
-            self._draw_label(g, panel, w, h, index)
+            # Label (positioned relative to content, not cell)
+            self._draw_label(g, panel, content_w, content_h, offset_x, offset_y, index)
         finally:
             src_doc.close()
 
@@ -125,7 +152,14 @@ class SVGComposer:
         return f"data:{mime};base64,{b64}"
 
     def _draw_label(
-        self, parent: etree.Element, panel: Panel, w: float, h: float, index: int
+        self,
+        parent: etree.Element,
+        panel: Panel,
+        content_w: float,
+        content_h: float,
+        offset_x: float,
+        offset_y: float,
+        index: int,
     ):
         style = panel.label_style if panel.label_style else self.layout.page.label
         if not style.enabled:
@@ -139,9 +173,9 @@ class SVGComposer:
         if style.uppercase:
             text_str = text_str.upper()
 
-        # Offset (relative to panel top-left, which is 0,0 inside the group)
-        x = mm_to_pt(style.offset_x_mm)
-        y = mm_to_pt(style.offset_y_mm)
+        # Offset relative to the content position
+        x = offset_x + mm_to_pt(style.offset_x_mm)
+        y = offset_y + mm_to_pt(style.offset_y_mm)
 
         # Create text element
         txt = etree.SubElement(parent, "text")

{figquilt-0.1.2 → figquilt-0.1.4}/src/figquilt/layout.py

@@ -1,7 +1,10 @@
-from typing import Optional, List, Tuple, Union
+from typing import Literal, Optional, List
 from pathlib import Path
 from pydantic import BaseModel, Field, field_validator
 
+FitMode = Literal["contain", "cover"]
+
+
 class LabelStyle(BaseModel):
     enabled: bool = True
     auto_sequence: bool = True
@@ -12,6 +15,7 @@ class LabelStyle(BaseModel):
     bold: bool = True
     uppercase: bool = True
 
+
 class Panel(BaseModel):
     id: str
     file: Path
@@ -19,6 +23,7 @@ class Panel(BaseModel):
     y: float
     width: float
     height: Optional[float] = None  # If None, compute from aspect ratio
+    fit: FitMode = "contain"
     label: Optional[str] = None
     label_style: Optional[LabelStyle] = None
 
@@ -29,6 +34,7 @@ class Panel(BaseModel):
         # but we could add it if desired. The parser/logic will check it.
         return v
 
+
 class Page(BaseModel):
     width: float
     height: float
@@ -37,6 +43,7 @@ class Page(BaseModel):
     background: Optional[str] = "white"
     label: LabelStyle = Field(default_factory=LabelStyle)
 
+
 class Layout(BaseModel):
     page: Page
     panels: List[Panel]

figquilt-0.1.4/src/figquilt/units.py

@@ -0,0 +1,70 @@
+def mm_to_pt(mm: float) -> float:
+    """Converts millimeters to points (1 inch = 25.4 mm = 72 pts)."""
+    return mm * 72 / 25.4
+
+
+def pt_to_mm(pt: float) -> float:
+    """Converts points to millimeters."""
+    return pt * 25.4 / 72
+
+
+def inches_to_pt(inches: float) -> float:
+    """Converts inches to points (1 inch = 72 pts)."""
+    return inches * 72
+
+
+def to_pt(value: float, units: str) -> float:
+    """Convert a value from the given units to points."""
+    if units == "mm":
+        return mm_to_pt(value)
+    elif units == "inches":
+        return inches_to_pt(value)
+    elif units == "pt":
+        return value
+    else:
+        raise ValueError(f"Unknown unit: {units}")
+
+
+def calculate_fit(
+    src_aspect: float, cell_w: float, cell_h: float, fit_mode: str
+) -> tuple[float, float, float, float]:
+    """
+    Calculate content dimensions and offset based on fit mode.
+
+    Args:
+        src_aspect: Source aspect ratio (height / width)
+        cell_w: Cell width in points
+        cell_h: Cell height in points
+        fit_mode: "contain" or "cover"
+
+    Returns:
+        Tuple of (content_w, content_h, offset_x, offset_y)
+    """
+    cell_aspect = cell_h / cell_w
+
+    if fit_mode == "cover":
+        # Scale to cover entire cell (may crop)
+        if src_aspect > cell_aspect:
+            # Source is taller: scale by width, crop top/bottom
+            content_w = cell_w
+            content_h = cell_w * src_aspect
+        else:
+            # Source is wider: scale by height, crop left/right
+            content_h = cell_h
+            content_w = cell_h / src_aspect
+    else:  # contain (default)
+        # Scale to fit within cell, preserving aspect ratio
+        if src_aspect > cell_aspect:
+            # Source is taller: fit by height
+            content_h = cell_h
+            content_w = cell_h / src_aspect
+        else:
+            # Source is wider: fit by width
+            content_w = cell_w
+            content_h = cell_w * src_aspect
+
+    # Center in cell
+    offset_x = (cell_w - content_w) / 2
+    offset_y = (cell_h - content_h) / 2
+
+    return content_w, content_h, offset_x, offset_y

figquilt-0.1.2/src/figquilt/units.py

@@ -1,7 +0,0 @@
-def mm_to_pt(mm: float) -> float:
-    """Converts millimeters to points (1 inch = 25.4 mm = 72 pts)."""
-    return mm * 72 / 25.4
-
-def pt_to_mm(pt: float) -> float:
-    """Converts points to millimeters."""
-    return pt * 25.4 / 72