figquilt 0.1.0__py3-none-any.whl

figquilt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

figquilt/cli.py

@@ -0,0 +1,65 @@
+import argparse
+import sys
+from pathlib import Path
+from .parser import parse_layout
+from .errors import FigQuiltError
+
+def main():
+    parser = argparse.ArgumentParser(description="FigQuilt: Compose figures from multiple panels.")
+    parser.add_argument("layout", type=Path, help="Path to layout YAML file")
+    parser.add_argument("output", type=Path, help="Path to output file (PDF/SVG/PNG)")
+    parser.add_argument("--format", choices=["pdf", "svg", "png"], help="Override output format")
+    parser.add_argument("--check", action="store_true", help="Validate layout only")
+    parser.add_argument("--verbose", action="store_true", help="Enable verbose output")
+    
+    args = parser.parse_args()
+
+    try:
+        layout = parse_layout(args.layout)
+        print(f"Layout parsed successfully: {args.layout}")
+        print(f"Page size: {layout.page.width}x{layout.page.height} {layout.page.units}")
+        print(f"Panels: {len(layout.panels)}")
+        
+        if args.check:
+            sys.exit(0)
+
+        # Determine output format
+        suffix = args.output.suffix.lower()
+        fmt = args.format or suffix.lstrip('.')
+        
+        if fmt == 'pdf':
+            from .compose_pdf import PDFComposer
+            composer = PDFComposer(layout)
+            composer.compose(args.output)
+            print(f"Successfully created: {args.output}")
+        
+        elif fmt == 'svg':
+            from .compose_svg import SVGComposer
+            composer = SVGComposer(layout)
+            composer.compose(args.output)
+            print(f"Successfully created: {args.output}")
+            
+        elif fmt == 'png':
+            from .compose_pdf import PDFComposer
+            composer = PDFComposer(layout)
+            doc = composer.build()
+            # Rasterize first page
+            page = doc[0]
+            pix = page.get_pixmap(dpi=layout.page.dpi)
+            pix.save(str(args.output))
+            doc.close()
+            print(f"Successfully created: {args.output}")
+            
+        else:
+            print(f"Unsupported format: {fmt}", file=sys.stderr)
+            sys.exit(1)
+
+    except FigQuiltError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

figquilt/compose_pdf.py

@@ -0,0 +1,143 @@
+import fitz
+from pathlib import Path
+from .layout import Layout, Panel
+from .units import mm_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)
+
+    def compose(self, output_path: Path):
+        doc = self.build()
+        doc.save(str(output_path))
+        doc.close()
+
+    def build(self) -> fitz.Document:
+        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)
+
+        # Draw panels
+        for i, panel in enumerate(self.layout.panels):
+            self._place_panel(doc, 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
+        x = mm_to_pt(panel.x)
+        y = mm_to_pt(panel.y)
+        w = mm_to_pt(panel.width)
+        
+        # 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}")
+
+        # 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
+
+        aspect = src_rect.height / src_rect.width
+        
+        if panel.height is not None:
+             h = mm_to_pt(panel.height)
+        else:
+            h = w * aspect
+
+        rect = fitz.Rect(x, y, x + w, y + h)
+
+        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)
+             page.show_pdf_page(rect, src_pdf, 0)
+        else:
+            # Insert as image (works for PNG/JPEG)
+            page.insert_image(rect, filename=panel.file)
+
+        # 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...
+        
+        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.
+        
+        pos_x = rect.x0 + mm_to_pt(style.offset_x_mm)
+        raw_y = rect.y0 + mm_to_pt(style.offset_y_mm)
+        
+        # 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
+
+        # Font - PyMuPDF supports base 14 fonts by name
+        fontname = "helv"  # default mapping for Helvetica
+        if style.bold:
+            fontname = "HeBo" # Helvetica-Bold
+        
+        # Insert text
+        page.insert_text((pos_x, pos_y), text, fontsize=style.font_size_pt, fontname=fontname)

figquilt/compose_svg.py

@@ -0,0 +1,153 @@
+from pathlib import Path
+import base64
+from lxml import etree
+from .layout import Layout, Panel
+from .units import mm_to_pt
+from .errors import FigQuiltError
+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)
+
+    def compose(self, output_path: Path):
+        # Create root SVG element
+        nsmap = {None: "http://www.w3.org/2000/svg", "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")
+        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)
+
+        # Draw panels
+        for i, panel in enumerate(self.layout.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):
+        x = mm_to_pt(panel.x)
+        y = mm_to_pt(panel.y)
+        w = mm_to_pt(panel.width)
+        
+        # Determine content sizing
+        # For simplicity in V0, relying on fitz for aspect ratio of all inputs (robust)
+        try:
+             src_doc = fitz.open(panel.file)
+             src_page = src_doc[0]
+             src_rect = src_page.rect
+             aspect = src_rect.height / src_rect.width
+        except Exception as e:
+            raise FigQuiltError(f"Failed to inspect panel {panel.file}: {e}")
+
+        if panel.height is not None:
+            h = mm_to_pt(panel.height)
+        else:
+            h = w * aspect
+
+        # Group for the panel
+        g = etree.SubElement(root, "g")
+        g.set("transform", f"translate({x}, {y})")
+        
+        # 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("{http://www.w3.org/1999/xlink}href", data_uri)
+        else:
+            # PDF or Raster Image
+            # For PDF, we rasterize to PNG (easiest for SVG compatibility without huge libs) or embed as image/pdf?
+            # Browsers don't support image/pdf in SVG.
+            # So if PDF, convert to PNG.
+            # 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) # Use decent DPI
+                 data = pix.tobytes("png")
+                 # We can't use _get_data_uri directly on file, we have bytes
+                 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("width", str(w))
+            img.set("height", str(h))
+            img.set("{http://www.w3.org/1999/xlink}href", data_uri)
+
+        # Label
+        self._draw_label(g, panel, w, h, index)
+
+    def _get_data_uri(self, path: Path, mime: str) -> str:
+        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, w: float, h: 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)
+        if not text_str:
+            return
+        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)
+        
+        # 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

figquilt/errors.py

@@ -0,0 +1,11 @@
+class FigQuiltError(Exception):
+    """Base exception for figquilt."""
+    pass
+
+class LayoutError(FigQuiltError):
+    """Raised when there is an issue with the layout configuration."""
+    pass
+
+class AssetMissingError(FigQuiltError):
+    """Raised when an input file cannot be found."""
+    pass

figquilt/images.py

@@ -0,0 +1,27 @@
+from pathlib import Path
+from typing import Tuple, Optional
+from PIL import Image
+import fitz
+
+def get_image_size(path: Path) -> Tuple[float, float]:
+    """Returns (width, height) in pixels/points."""
+    try:
+        with Image.open(path) as img:
+            return float(img.width), float(img.height)
+    except Exception:
+        # Try fitz for PDF/SVG
+        try:
+            doc = fitz.open(path)
+            page = doc[0]
+            return page.rect.width, page.rect.height
+        except Exception:
+            raise ValueError(f"Could not determine size of {path}")
+
+def is_image(path: Path) -> bool:
+    """Checks if the file is a raster image supported by Pillow."""
+    try:
+        with Image.open(path) as img:
+            img.verify()
+        return True
+    except Exception:
+        return False

figquilt/layout.py

@@ -0,0 +1,42 @@
+from typing import Optional, List, Tuple, Union
+from pathlib import Path
+from pydantic import BaseModel, Field, field_validator
+
+class LabelStyle(BaseModel):
+    enabled: bool = True
+    auto_sequence: bool = True
+    font_family: str = "Helvetica"
+    font_size_pt: float = 8.0
+    offset_x_mm: float = 2.0
+    offset_y_mm: float = 2.0
+    bold: bool = True
+    uppercase: bool = True
+
+class Panel(BaseModel):
+    id: str
+    file: Path
+    x: float
+    y: float
+    width: float
+    height: Optional[float] = None  # If None, compute from aspect ratio
+    label: Optional[str] = None
+    label_style: Optional[LabelStyle] = None
+
+    @field_validator("file")
+    @classmethod
+    def validate_file(cls, v: Path) -> Path:
+        # We don't check existence here to allow validation without side effects,
+        # but we could add it if desired. The parser/logic will check it.
+        return v
+
+class Page(BaseModel):
+    width: float
+    height: float
+    units: str = "mm"
+    dpi: int = 300
+    background: Optional[str] = "white"
+    label: LabelStyle = Field(default_factory=LabelStyle)
+
+class Layout(BaseModel):
+    page: Page
+    panels: List[Panel]

figquilt/parser.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+import yaml
+from .layout import Layout
+from .errors import LayoutError, AssetMissingError
+
+def parse_layout(layout_path: Path) -> Layout:
+    """Parses a YAML layout file and returns a Layout object."""
+    if not layout_path.exists():
+        raise LayoutError(f"Layout file not found: {layout_path}")
+
+    try:
+        with open(layout_path, 'r') as f:
+            data = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        raise LayoutError(f"Failed to parse YAML: {e}")
+
+    try:
+        layout = Layout(**data)
+    except Exception as e:
+        raise LayoutError(f"Layout validation failed: {e}")
+
+    # Validate assets exist relative to the layout file
+    base_dir = layout_path.parent
+    for panel in layout.panels:
+        # Resolve path relative to layout file if not absolute
+        if not panel.file.is_absolute():
+            panel.file = base_dir / panel.file
+        
+        if not panel.file.exists():
+            raise AssetMissingError(f"Asset for panel '{panel.id}' not found: {panel.file}")
+
+    return layout

figquilt/units.py

@@ -0,0 +1,7 @@
+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

figquilt-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.3
+Name: figquilt
+Version: 0.1.0
+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>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: matplotlib>=3.10.7
+Requires-Dist: pillow>=12.0.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pymupdf>=1.26.6
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: seaborn>=0.13.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/yy/figquilt
+Project-URL: Repository, https://github.com/yy/figquilt
+Description-Content-Type: text/markdown
+
+# figquilt
+
+**Figure quilter**: A CLI tool to compositing multiple figures (PDF, SVG, PNG) into a publication-ready figure layout.
+
+`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.
+
+## Features
+
+- **Precise Layout**: Define exact physical dimensions (mm) for the page and panels.
+- **Mixed Media**: Combine PDF, SVG, and PNG inputs in one figure.
+- **Automated Labeling**: Automatically add subfigure labels (A, B, C...) with consistent styling.
+- **Reproducible**: Layouts are defined in version-controllable text files (YAML).
+- **Language Agnostic**: It is a CLI tool, so it works with outputs from any tool (R, Python, Julia, Inkscape, etc.).
+
+## Installation
+
+This project uses `uv` for dependency management.
+
+```bash
+# Clone the repository
+git clone https://github.com/yy/figquilt.git
+cd figquilt
+
+# Install dependencies and set up the environment
+uv sync
+
+# Install the package in editable mode
+uv pip install -e .
+```
+
+## Usage
+
+Define a layout in a YAML file (e.g., `figure1.yaml`):
+
+```yaml
+page:
+  width: 180  # mm
+  height: 120 # mm
+  
+panels:
+  - id: A
+    file: "plots/scatter.pdf"
+    width: 80
+    x: 0
+    y: 0
+  - id: B
+    file: "diagrams/schematic.svg"
+    width: 80
+    x: 90
+    y: 0
+```
+
+Run `figquilt` to generate the figure:
+
+```bash
+figquilt figure1.yaml figure1.pdf
+```

figquilt-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+figquilt/__init__.py,sha256=91447944015cec709e8aa7655f7e9d64e1e4508e7023a57fe3746911c0fc6fed,22
+figquilt/cli.py,sha256=481535c3c2d77a73692d76c1be8dfd02056a2b20edb7e9877edca0edf73d67ab,2352
+figquilt/compose_pdf.py,sha256=4da4d5f9b656cd1da6c1b58e3e92a18955d60aa498bd1720050fc6a5988f0e4c,5385
+figquilt/compose_svg.py,sha256=2a4f01369be6c4acca62f823967bc3027b9b341b339e55391186ed5eb6f0a5fb,5921
+figquilt/errors.py,sha256=6f4001dcae85d2171f7aa7df4161926771dbe8c21068ccb70a7865298f05cf2b,298
+figquilt/images.py,sha256=c613655fb3a0790fca98182c558c584e632a8822225220a5feb6080c7c68eb9e,815
+figquilt/layout.py,sha256=44514c72f8883afe02f5dd05e674410440dc52c40966a8028f1d9693d4be3364,1159
+figquilt/parser.py,sha256=d33d21178721072bbf681be940312b5fda0275f451fca3be2affad707f80a7fb,1065
+figquilt/units.py,sha256=0c1b6b3f7380fb8ebf51ae81fb093c1830ae4a240b9151191333a3b0af16cd84,233
+figquilt-0.1.0.dist-info/WHEEL,sha256=76443c98c0efcfdd1191eac5fa1d8223dba1c474dbd47676674a255e7ca48770,79
+figquilt-0.1.0.dist-info/entry_points.txt,sha256=8f70ce07f585bed28aca569052c7f0029384ac67c5e738faeb0daeb31695bc85,48
+figquilt-0.1.0.dist-info/METADATA,sha256=91ec1ccc28fee0be464922bae83d7f154447d1ff69c014b64b007ef949ef640b,2518
+figquilt-0.1.0.dist-info/RECORD,,

figquilt-0.1.0.dist-info/WHEEL

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

figquilt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+figquilt = figquilt.cli:main
+