figquilt 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

figquilt/base_composer.py

@@ -0,0 +1,163 @@
+"""Base class for figure composers with shared functionality."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import NamedTuple
+
+import fitz
+
+from .errors import FigQuiltError
+from .grid import resolve_layout
+from .layout import Layout, Panel
+from .units import calculate_fit, to_pt
+
+
+class SourceInfo(NamedTuple):
+    """Information about a source file."""
+
+    doc: fitz.Document
+    aspect_ratio: float
+
+
+class ContentRect(NamedTuple):
+    """Computed content rectangle within a cell."""
+
+    x: float
+    y: float
+    width: float
+    height: float
+    offset_x: float
+    offset_y: float
+
+
+class BaseComposer(ABC):
+    """Base class for PDF and SVG composers with shared initialization and helpers."""
+
+    def __init__(self, layout: Layout):
+        self.layout = layout
+        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)
+        self.margin_pt = to_pt(layout.page.margin, self.units)
+
+    @abstractmethod
+    def compose(self, output_path: Path) -> None:
+        """Compose the layout and write to output file."""
+        pass
+
+    def get_panels(self) -> list[Panel]:
+        """Resolve and return the list of panels from the layout."""
+        return resolve_layout(self.layout)
+
+    def open_source(self, panel: Panel) -> SourceInfo:
+        """
+        Open a source file and return its document and aspect ratio.
+
+        Args:
+            panel: Panel containing the file path
+
+        Returns:
+            SourceInfo with the opened document and aspect ratio
+
+        Raises:
+            FigQuiltError: If the file cannot be opened
+        """
+        try:
+            src_doc = fitz.open(panel.file)
+        except Exception as e:
+            raise FigQuiltError(f"Failed to open panel file {panel.file}: {e}")
+
+        src_page = src_doc[0]
+        src_rect = src_page.rect
+        aspect_ratio = src_rect.height / src_rect.width
+
+        return SourceInfo(doc=src_doc, aspect_ratio=aspect_ratio)
+
+    def calculate_content_rect(self, panel: Panel, src_aspect: float) -> ContentRect:
+        """
+        Calculate the content rectangle for a panel.
+
+        Args:
+            panel: Panel with position and size
+            src_aspect: Source aspect ratio (height / width)
+
+        Returns:
+            ContentRect with position, dimensions, and offsets
+        """
+        x = to_pt(panel.x, self.units) + self.margin_pt
+        y = to_pt(panel.y, self.units) + self.margin_pt
+        w = to_pt(panel.width, self.units)
+
+        if panel.height is not None:
+            h = to_pt(panel.height, self.units)
+        else:
+            h = w * src_aspect
+
+        content_w, content_h, offset_x, offset_y = calculate_fit(
+            src_aspect, w, h, panel.fit, panel.align
+        )
+
+        return ContentRect(
+            x=x,
+            y=y,
+            width=content_w,
+            height=content_h,
+            offset_x=offset_x,
+            offset_y=offset_y,
+        )
+
+    def get_label_text(self, panel: Panel, index: int) -> str | None:
+        """
+        Get the label text for a panel.
+
+        Args:
+            panel: Panel with optional label override
+            index: Panel index for auto-sequencing
+
+        Returns:
+            Label text or None if labels are disabled
+        """
+        style = panel.label_style if panel.label_style else self.layout.page.label
+
+        if not style.enabled:
+            return None
+
+        text = panel.label
+        if text is None and style.auto_sequence:
+            text = chr(65 + index)  # A, B, C...
+
+        if not text:
+            return None
+
+        if style.uppercase:
+            text = text.upper()
+
+        return text
+
+    def parse_color(self, color_str: str) -> tuple[float, float, float] | None:
+        """
+        Parse a color string to RGB tuple (0-1 range).
+
+        Supports hex colors (#rrggbb) and CSS color names via PIL.
+
+        Args:
+            color_str: Color string (e.g., "#f0f0f0", "white")
+
+        Returns:
+            RGB tuple with values 0-1, or None if parsing fails
+        """
+        if color_str.startswith("#"):
+            h = color_str.lstrip("#")
+            try:
+                rgb = tuple(int(h[i : i + 2], 16) / 255.0 for i in (0, 2, 4))
+                return rgb  # type: ignore
+            except (ValueError, IndexError):
+                return None
+
+        try:
+            from PIL import ImageColor
+
+            rgb = ImageColor.getrgb(color_str)
+            return tuple(c / 255.0 for c in rgb)  # type: ignore
+        except (ValueError, ImportError):
+            return None

figquilt/compose_pdf.py

@@ -1,19 +1,23 @@
-import fitz
+"""PDF composer using PyMuPDF (fitz)."""
+
 from pathlib import Path
+
+import fitz
+
+from .base_composer import BaseComposer
 from .layout import Layout, Panel
 from .units import to_pt
-from .errors import FigQuiltError
+
+# PyMuPDF font name mappings
+_FONT_REGULAR = "helv"  # Helvetica
+_FONT_BOLD = "HeBo"  # Helvetica-Bold
 
 
-class PDFComposer:
+class PDFComposer(BaseComposer):
     def __init__(self, layout: Layout):
-        self.layout = layout
-        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)
-        self.margin_pt = to_pt(layout.page.margin, self.units)
+        super().__init__(layout)
 
-    def compose(self, output_path: Path):
+    def compose(self, output_path: Path) -> None:
         doc = self.build()
         doc.save(str(output_path))
         doc.close()
@@ -22,152 +26,77 @@ class PDFComposer:
         doc = fitz.open()
         page = doc.new_page(width=self.width_pt, height=self.height_pt)
 
-        # Draw background if specified
-        if self.layout.page.background:
-            # simple color parsing: strict names or hex?
-            # PyMuPDF draw_rect color expects sequence of floats (0..1) or nothing.
-            # We need to robustly parse the color string from layout (e.g. "white", "#f0f0f0").
-            # fitz.utils.getColor? No, fitz doesn't have a robust color parser built-in for all CSS names.
-            # But the user example uses "#f0f0f0".
-            # Minimal hex parser:
-            col = self._parse_color(self.layout.page.background)
-            if col:
-                page.draw_rect(page.rect, color=col, fill=col)
-
-        # Get panels (resolves grid layout if needed)
-        from .grid import resolve_layout
-
-        panels = resolve_layout(self.layout)
+        self._draw_background(page)
+
+        panels = self.get_panels()
         for i, panel in enumerate(panels):
-            self._place_panel(doc, page, panel, index=i)
+            self._place_panel(page, panel, index=i)
 
         return doc
 
-    def _parse_color(self, color_str: str):
-        # Very basic hex support
-        if color_str.startswith("#"):
-            h = color_str.lstrip("#")
-            try:
-                rgb = tuple(int(h[i : i + 2], 16) / 255.0 for i in (0, 2, 4))
-                return rgb
-            except:
-                return None
-        # Basic name support mapping could be added here
-        # For now, just support hex or fallback to None (skip)
-        # Using PIL ImageColor is an option if we import it, but we want minimal dep for this file?
-        # We process images, so PIL is available.
-        try:
-            from PIL import ImageColor
-
-            rgb = ImageColor.getrgb(color_str)
-            return tuple(c / 255.0 for c in rgb)
-        except:
-            return None
-
-    def _place_panel(
-        self, doc: fitz.Document, page: fitz.Page, panel: Panel, index: int
-    ):
-        # Calculate position and size first, offset by page margin
-        x = to_pt(panel.x, self.units) + self.margin_pt
-        y = to_pt(panel.y, self.units) + self.margin_pt
-        w = to_pt(panel.width, self.units)
-
-        # Determine height from aspect ratio if needed
-        # We need to open the source to get aspect ratio
-        try:
-            # fitz.open can handle PDF, PNG, JPEG, SVG...
-            src_doc = fitz.open(panel.file)
-        except Exception as e:
-            raise FigQuiltError(f"Failed to open panel file {panel.file}: {e}")
+    def _draw_background(self, page: fitz.Page) -> None:
+        """Draw background color if specified."""
+        if not self.layout.page.background:
+            return
+
+        col = self.parse_color(self.layout.page.background)
+        if col:
+            page.draw_rect(page.rect, color=col, fill=col)
+
+    def _place_panel(self, page: fitz.Page, panel: Panel, index: int) -> None:
+        """Place a panel on the page."""
+        source_info = self.open_source(panel)
 
         try:
-            # Get source dimension
-            if src_doc.is_pdf:
-                src_page = src_doc[0]
-                src_rect = src_page.rect
-            else:
-                # For images/SVG, fitz doc acts like a list of pages too?
-                # Yes, usually page[0] is the image/svg content.
-                src_page = src_doc[0]
-                src_rect = src_page.rect
-
-            src_aspect = src_rect.height / src_rect.width
-
-            # Calculate cell height
-            if panel.height is not None:
-                h = to_pt(panel.height, self.units)
-            else:
-                # 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
-            )
+            content_rect = self.calculate_content_rect(panel, source_info.aspect_ratio)
             rect = fitz.Rect(
-                x + offset_x,
-                y + offset_y,
-                x + offset_x + content_w,
-                y + offset_y + content_h,
+                content_rect.x + content_rect.offset_x,
+                content_rect.y + content_rect.offset_y,
+                content_rect.x + content_rect.offset_x + content_rect.width,
+                content_rect.y + content_rect.offset_y + content_rect.height,
             )
 
-            if src_doc.is_pdf:
-                page.show_pdf_page(rect, src_doc, 0)
-            elif panel.file.suffix.lower() == ".svg":
-                # Convert SVG to PDF in memory to allow vector embedding
-                pdf_bytes = src_doc.convert_to_pdf()
-                src_pdf = fitz.open("pdf", pdf_bytes)
-                try:
-                    page.show_pdf_page(rect, src_pdf, 0)
-                finally:
-                    src_pdf.close()
-            else:
-                # Insert as image (works for PNG/JPEG)
-                page.insert_image(rect, filename=panel.file)
+            self._embed_content(page, rect, source_info.doc, panel)
         finally:
-            src_doc.close()
+            source_info.doc.close()
 
-        # Labels
         self._draw_label(page, panel, rect, index)
 
-    def _draw_label(self, page: fitz.Page, panel: Panel, rect: fitz.Rect, index: int):
-        # Determine effective label settings
-        style = panel.label_style if panel.label_style else self.layout.page.label
-
-        if not style.enabled:
-            return
-
-        text = panel.label
-        if text is None and style.auto_sequence:
-            text = chr(65 + index)  # A, B, C...
-
+    def _embed_content(
+        self, page: fitz.Page, rect: fitz.Rect, src_doc: fitz.Document, panel: Panel
+    ) -> None:
+        """Embed the source content into the page at the given rect."""
+        if src_doc.is_pdf:
+            page.show_pdf_page(rect, src_doc, 0)
+        elif panel.file.suffix.lower() == ".svg":
+            # Convert SVG to PDF in memory for vector preservation
+            pdf_bytes = src_doc.convert_to_pdf()
+            src_pdf = fitz.open("pdf", pdf_bytes)
+            try:
+                page.show_pdf_page(rect, src_pdf, 0)
+            finally:
+                src_pdf.close()
+        else:
+            # Insert as image (works for PNG/JPEG)
+            page.insert_image(rect, filename=panel.file)
+
+    def _draw_label(
+        self, page: fitz.Page, panel: Panel, rect: fitz.Rect, index: int
+    ) -> None:
+        """Draw the label for a panel."""
+        text = self.get_label_text(panel, index)
         if not text:
             return
 
-        if style.uppercase:
-            text = text.upper()
-
-        # Position logic
-        # Design doc: offset is relative to top-left.
-        # SVG implementation uses 'hanging' baseline, so (0,0) is top-left of text char.
-        # PyMuPDF insert_text uses 'baseline', so (0,0) is bottom-left of text char.
-        # We need to shift Y down by approximately the font sizing to match SVG visual.
+        style = panel.label_style if panel.label_style else self.layout.page.label
 
+        # Position: offset relative to top-left of content rect
+        # PyMuPDF uses baseline positioning, so add font_size to Y
         pos_x = rect.x0 + to_pt(style.offset_x, self.units)
-        raw_y = rect.y0 + to_pt(style.offset_y, self.units)
-
-        # Approximate baseline shift: font_size
-        # (A more precise way uses font.ascender, but for basic standard fonts, size is decent proxy for visual top->baseline)
-        pos_y = raw_y + style.font_size_pt
+        pos_y = rect.y0 + to_pt(style.offset_y, self.units) + style.font_size_pt
 
-        # Font - PyMuPDF supports base 14 fonts by name
-        fontname = "helv"  # default mapping for Helvetica
-        if style.bold:
-            fontname = "HeBo"  # Helvetica-Bold
+        fontname = _FONT_BOLD if style.bold else _FONT_REGULAR
 
-        # Insert text
         page.insert_text(
             (pos_x, pos_y), text, fontsize=style.font_size_pt, fontname=fontname
         )

figquilt/compose_svg.py

@@ -1,200 +1,166 @@
-from pathlib import Path
+"""SVG composer using lxml."""
+
 import base64
+from pathlib import Path
+
 from lxml import etree
+
+from .base_composer import BaseComposer
 from .layout import Layout, Panel
 from .units import to_pt
-from .errors import FigQuiltError
-import fitz
 
 
-class SVGComposer:
+class SVGComposer(BaseComposer):
     def __init__(self, layout: Layout):
-        self.layout = layout
-        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)
-        self.margin_pt = to_pt(layout.page.margin, self.units)
-
-    def compose(self, output_path: Path):
-        # Create root SVG element
+        super().__init__(layout)
+
+    def compose(self, output_path: Path) -> None:
         nsmap = {
             None: "http://www.w3.org/2000/svg",
             "xlink": "http://www.w3.org/1999/xlink",
         }
         root = etree.Element("svg", nsmap=nsmap)
-        # SVG uses "in" for inches, "pt" for points, "mm" for millimeters
+
+        # Set SVG dimensions
         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")
 
-        if self.layout.page.background:
-            # Draw background
-            bg = etree.SubElement(root, "rect")
-            bg.set("width", "100%")
-            bg.set("height", "100%")
-            bg.set("fill", self.layout.page.background)
+        self._draw_background(root)
 
-        # Get panels (resolves grid layout if needed)
-        from .grid import resolve_layout
-
-        panels = resolve_layout(self.layout)
+        panels = self.get_panels()
         for i, panel in enumerate(panels):
             self._place_panel(root, panel, i)
 
-        # Write to file
         tree = etree.ElementTree(root)
         with open(output_path, "wb") as f:
             tree.write(f, pretty_print=True, xml_declaration=True, encoding="utf-8")
 
-    def _place_panel(self, root: etree.Element, panel: Panel, index: int):
-        # Offset by page margin
-        x = to_pt(panel.x, self.units) + self.margin_pt
-        y = to_pt(panel.y, self.units) + self.margin_pt
-        w = to_pt(panel.width, self.units)
-
-        # Determine content sizing
-        # For simplicity in V0, relying on fitz for aspect ratio of all inputs (robust)
-        try:
-            src_doc = fitz.open(panel.file)
-        except Exception as e:
-            raise FigQuiltError(f"Failed to inspect panel {panel.file}: {e}")
-
-        try:
-            src_page = src_doc[0]
-            src_rect = src_page.rect
-            src_aspect = src_rect.height / src_rect.width
+    def _draw_background(self, root: etree.Element) -> None:
+        """Draw background color if specified."""
+        if not self.layout.page.background:
+            return
 
-            if panel.height is not None:
-                h = to_pt(panel.height, self.units)
-            else:
-                h = w * src_aspect
+        bg = etree.SubElement(root, "rect")
+        bg.set("width", "100%")
+        bg.set("height", "100%")
+        bg.set("fill", self.layout.page.background)
 
-            # Calculate content dimensions using fit mode
-            from .units import calculate_fit
+    def _place_panel(self, root: etree.Element, panel: Panel, index: int) -> None:
+        """Place a panel on the SVG."""
+        source_info = self.open_source(panel)
 
-            content_w, content_h, offset_x, offset_y = calculate_fit(
-                src_aspect, w, h, panel.fit
-            )
+        try:
+            content_rect = self.calculate_content_rect(panel, source_info.aspect_ratio)
 
-            # Group for the panel
+            # Create group for the panel
             g = etree.SubElement(root, "g")
-            g.set("transform", f"translate({x}, {y})")
+            g.set("transform", f"translate({content_rect.x}, {content_rect.y})")
 
-            # For cover mode, add a clip path to crop the overflow
+            # Set up clipping for cover mode
+            clip_id = None
             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
-                data_uri = self._get_data_uri(panel.file, "image/svg+xml")
-                img = etree.SubElement(g, "image")
-                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)
-                # Browsers don't support image/pdf in SVG.
-                # If PNG/JPG, embed directly.
-
-                mime = "image/png"
-                if suffix in [".jpg", ".jpeg"]:
-                    mime = "image/jpeg"
-                    data_path = panel.file
-                elif suffix == ".png":
-                    mime = "image/png"
-                    data_path = panel.file
-                elif suffix == ".pdf":
-                    # Rasterize page to PNG
-                    pix = src_page.get_pixmap(dpi=300)
-                    data = pix.tobytes("png")
-                    b64 = base64.b64encode(data).decode("utf-8")
-                    data_uri = f"data:image/png;base64,{b64}"
-                    data_path = None  # signal that we have URI
-                else:
-                    # Fallback
-                    mime = "application/octet-stream"
-                    data_path = panel.file
-
-                if data_path:
-                    data_uri = self._get_data_uri(data_path, mime)
-
-                img = etree.SubElement(g, "image")
-                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 (positioned relative to content, not cell)
-            self._draw_label(g, panel, content_w, content_h, offset_x, offset_y, index)
+                clip_id = self._add_clip_path(
+                    g,
+                    panel.id,
+                    to_pt(panel.width, self.units),
+                    content_rect.height
+                    if panel.height is None
+                    else to_pt(panel.height, self.units),
+                )
+
+            # Embed content
+            self._embed_content(g, panel, content_rect, source_info.doc[0], clip_id)
+
+            # Draw label
+            self._draw_label(g, panel, content_rect, index)
         finally:
-            src_doc.close()
+            source_info.doc.close()
+
+    def _add_clip_path(
+        self, g: etree.Element, panel_id: str, width: float, height: float
+    ) -> str:
+        """Add a clip path for cover mode and return its ID."""
+        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(width))
+        clip_rect.set("height", str(height))
+        return clip_id
+
+    def _embed_content(
+        self,
+        g: etree.Element,
+        panel: Panel,
+        content_rect,
+        src_page,
+        clip_id: str | None,
+    ) -> None:
+        """Embed the source content into the SVG group."""
+        suffix = panel.file.suffix.lower()
+
+        if suffix == ".svg":
+            data_uri = self._get_data_uri(panel.file, "image/svg+xml")
+        elif suffix in [".jpg", ".jpeg"]:
+            data_uri = self._get_data_uri(panel.file, "image/jpeg")
+        elif suffix == ".png":
+            data_uri = self._get_data_uri(panel.file, "image/png")
+        elif suffix == ".pdf":
+            # Rasterize PDF page to PNG
+            pix = src_page.get_pixmap(dpi=300)
+            data = pix.tobytes("png")
+            b64 = base64.b64encode(data).decode("utf-8")
+            data_uri = f"data:image/png;base64,{b64}"
+        else:
+            # Fallback for unknown types
+            data_uri = self._get_data_uri(panel.file, "application/octet-stream")
+
+        img = etree.SubElement(g, "image")
+        img.set("x", str(content_rect.offset_x))
+        img.set("y", str(content_rect.offset_y))
+        img.set("width", str(content_rect.width))
+        img.set("height", str(content_rect.height))
+        img.set("{http://www.w3.org/1999/xlink}href", data_uri)
+
+        if clip_id:
+            img.set("clip-path", f"url(#{clip_id})")
 
     def _get_data_uri(self, path: Path, mime: str) -> str:
+        """Read file and encode as data URI."""
         with open(path, "rb") as f:
             data = f.read()
         b64 = base64.b64encode(data).decode("utf-8")
         return f"data:{mime};base64,{b64}"
 
     def _draw_label(
-        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:
-            return
-
-        text_str = panel.label
-        if text_str is None and style.auto_sequence:
-            text_str = chr(65 + index)
+        self, parent: etree.Element, panel: Panel, content_rect, index: int
+    ) -> None:
+        """Draw the label for a panel."""
+        text_str = self.get_label_text(panel, index)
         if not text_str:
             return
-        if style.uppercase:
-            text_str = text_str.upper()
+
+        style = panel.label_style if panel.label_style else self.layout.page.label
 
         # Offset relative to the content position
-        x = offset_x + to_pt(style.offset_x, self.units)
-        y = offset_y + to_pt(style.offset_y, self.units)
+        x = content_rect.offset_x + to_pt(style.offset_x, self.units)
+        y = content_rect.offset_y + to_pt(style.offset_y, self.units)
 
-        # Create text element
         txt = etree.SubElement(parent, "text")
         txt.text = text_str
         txt.set("x", str(x))
         txt.set("y", str(y))
-
-        # Style
-        # Font family is tricky in SVG (system fonts).
         txt.set("font-family", style.font_family)
         txt.set("font-size", f"{style.font_size_pt}pt")
+
         if style.bold:
             txt.set("font-weight", "bold")
 
-        # Baseline alignment? SVG text y is usually baseline.
-        # If we want top-left of text at (x,y), we should adjust or use dominant-baseline.
-        txt.set("dominant-baseline", "hanging")  # Matches top-down coordinate logic
+        # Use hanging baseline so (x, y) is top-left of text
+        txt.set("dominant-baseline", "hanging")

figquilt/grid.py

@@ -58,6 +58,7 @@ def _resolve_node(
                 width=width,
                 height=height,
                 fit=node.fit,
+                align=node.align,
                 label=node.label,
                 label_style=node.label_style,
             )

figquilt/layout.py

@@ -4,6 +4,17 @@ from pathlib import Path
 from pydantic import BaseModel, Field, field_validator, model_validator
 
 FitMode = Literal["contain", "cover"]
+Alignment = Literal[
+    "center",
+    "top",
+    "bottom",
+    "left",
+    "right",
+    "top-left",
+    "top-right",
+    "bottom-left",
+    "bottom-right",
+]
 
 
 class LabelStyle(BaseModel):
@@ -38,6 +49,10 @@ class Panel(BaseModel):
         "contain",
         description="How to fit the figure: contain (preserve aspect) or cover (fill and clip)",
     )
+    align: Alignment = Field(
+        "center",
+        description="How to align content within cell when using contain fit mode",
+    )
     label: Optional[str] = Field(
         None, description="Override the auto-generated label text"
     )
@@ -76,6 +91,9 @@ class LayoutNode(BaseModel):
         None, description="Path to source file (PDF, SVG, or PNG)"
     )
     fit: FitMode = Field("contain", description="How to fit the figure in its cell")
+    align: Alignment = Field(
+        "center", description="How to align content within cell when using contain fit"
+    )
     label: Optional[str] = Field(
         None, description="Override the auto-generated label text"
     )

figquilt/units.py

@@ -20,17 +20,38 @@ def to_pt(value: float, units: str) -> float:
         raise ValueError(f"Unknown unit: {units}")
 
 
+# Alignment offset factors: (horizontal_factor, vertical_factor)
+# Multiply by (space_x, space_y) to get offset
+_ALIGNMENT_OFFSETS: dict[str, tuple[float, float]] = {
+    "center": (0.5, 0.5),
+    "top": (0.5, 0.0),
+    "bottom": (0.5, 1.0),
+    "left": (0.0, 0.5),
+    "right": (1.0, 0.5),
+    "top-left": (0.0, 0.0),
+    "top-right": (1.0, 0.0),
+    "bottom-left": (0.0, 1.0),
+    "bottom-right": (1.0, 1.0),
+}
+
+
 def calculate_fit(
-    src_aspect: float, cell_w: float, cell_h: float, fit_mode: str
+    src_aspect: float,
+    cell_w: float,
+    cell_h: float,
+    fit_mode: str,
+    align: str = "center",
 ) -> tuple[float, float, float, float]:
     """
-    Calculate content dimensions and offset based on fit mode.
+    Calculate content dimensions and offset based on fit mode and alignment.
 
     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"
+        align: Alignment within cell (center, top, bottom, left, right,
+               top-left, top-right, bottom-left, bottom-right)
 
     Returns:
         Tuple of (content_w, content_h, offset_x, offset_y)
@@ -58,8 +79,11 @@ def calculate_fit(
             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
+    # Calculate offsets based on alignment using lookup table
+    space_x = cell_w - content_w
+    space_y = cell_h - content_h
+    h_factor, v_factor = _ALIGNMENT_OFFSETS.get(align, (0.5, 0.5))
+    offset_x = space_x * h_factor
+    offset_y = space_y * v_factor
 
     return content_w, content_h, offset_x, offset_y

{figquilt-0.1.6.dist-info → figquilt-0.1.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: figquilt
-Version: 0.1.6
+Version: 0.1.8
 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>

figquilt-0.1.8.dist-info/RECORD

@@ -0,0 +1,15 @@
+figquilt/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+figquilt/base_composer.py,sha256=Mk16r7Gpo7M5e3ipHEDWBAbs75pp59f4uiF815d-9YQ,4659
+figquilt/cli.py,sha256=BK-Ump6TzH_cLe1ciSzwY1bUSQPBxPv96ipKEEKWFt4,7062
+figquilt/compose_pdf.py,sha256=u_nrWKo0Z6W8ToXhg5suf-e1tWGQFBPvmUg7sEQ-yPI,3425
+figquilt/compose_svg.py,sha256=qr3-wGeZezZje9SoApLiPdzntDlToD2fvZDK6kW_0TM,5806
+figquilt/errors.py,sha256=b0AB3K6F0hcfeqffQWGSZ3Hb6MIQaMy3CnhlKY8Fzys,298
+figquilt/grid.py,sha256=6Xf7-S4-Kghg9ZjIni8jBx1R5m0sjB59b6s0vXWSVjE,3084
+figquilt/images.py,sha256=xhNlX7OgeQ_KmBgsVYxYTmMqiCIiUiCl_rYIDHxo654,815
+figquilt/layout.py,sha256=492Cwf7sGNhMshvYu2LF3Q_CguRa31-2TLotq4fUNCI,6449
+figquilt/parser.py,sha256=lljHPplk8gYK_QHaQSOqAGPIBi04JEPB4cqseefr9kg,4029
+figquilt/units.py,sha256=hBq3SHvrAgfCinNvGnNDLrRQ0xAGxyGraRmp6UNrWxQ,2786
+figquilt-0.1.8.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+figquilt-0.1.8.dist-info/entry_points.txt,sha256=j3DOB_WFvtKKylaQUsfwApOErGfF5zj66w2usxaVvIU,48
+figquilt-0.1.8.dist-info/METADATA,sha256=TROdXq82uE-gwZzgD25WdlJTw_Uv2YtIdR5Ndzbj-3I,6217
+figquilt-0.1.8.dist-info/RECORD,,

{figquilt-0.1.6.dist-info → figquilt-0.1.8.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.8.12
+Generator: uv 0.8.24
 Root-Is-Purelib: true
 Tag: py3-none-any

figquilt-0.1.6.dist-info/RECORD

@@ -1,14 +0,0 @@
-figquilt/__init__.py,sha256=91447944015cec709e8aa7655f7e9d64e1e4508e7023a57fe3746911c0fc6fed,22
-figquilt/cli.py,sha256=04af949a9e93cc7fdc2ded5c892cf06356d44903c1c4fbfdea2a4a10429616de,7062
-figquilt/compose_pdf.py,sha256=20ac74b06df83f7db019a3686e8a5318c8744599c16100fd818177c60c2597e8,6401
-figquilt/compose_svg.py,sha256=8e8b65725ef37e6a66cff625ac34be0c3e87d263f9e03ce6b1fb1456f99d0754,7656
-figquilt/errors.py,sha256=6f4001dcae85d2171f7aa7df4161926771dbe8c21068ccb70a7865298f05cf2b,298
-figquilt/grid.py,sha256=b56aa9fabe023e9c9447d4d13c573a7ad64a60a1de38435fceb4429ecfaed00f,3050
-figquilt/images.py,sha256=c613655fb3a0790fca98182c558c584e632a8822225220a5feb6080c7c68eb9e,815
-figquilt/layout.py,sha256=c7c65eeacf1179ee25dcbac05d729ea0a1102ed6abffa7ee401f63099958aa61,6028
-figquilt/parser.py,sha256=9658c73e9964f2060afd01da4123aa0063c8062d382443c1e1caac79e7ebf648,4029
-figquilt/units.py,sha256=9f87b73643e39b54f1bd1011a8118d570ebab03c1bb4526169bbf6457e5a2b43,2020
-figquilt-0.1.6.dist-info/WHEEL,sha256=76443c98c0efcfdd1191eac5fa1d8223dba1c474dbd47676674a255e7ca48770,79
-figquilt-0.1.6.dist-info/entry_points.txt,sha256=8f70ce07f585bed28aca569052c7f0029384ac67c5e738faeb0daeb31695bc85,48
-figquilt-0.1.6.dist-info/METADATA,sha256=6f99e38c83ed059062ef8c3e79ab5ff233273930dd4d376ca01bb2e1668047d7,6217
-figquilt-0.1.6.dist-info/RECORD,,