decksmith 0.1.0__tar.gz

decksmith-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.3
+Name: decksmith
+Version: 0.1.0
+Summary: A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck.
+License: GPL-2.0-only
+Author: Julio Cabria
+Author-email: juliocabria@tutanota.com
+Requires-Python: >=3.13
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: dev
+Requires-Dist: click
+Requires-Dist: jval (==1.0.6)
+Requires-Dist: pandas
+Requires-Dist: pillow (>=11.3.0)
+Requires-Dist: poetry ; extra == "dev"
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: reportlab (>=4.4.3)
+Project-URL: Homepage, https://github.com/Julynx/decksmith
+Description-Content-Type: text/markdown
+
+# DeckSmith
+
+A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck.
+
+DeckSmith is ideal for automating the creation of all kinds of decks, including TCG decks, tarot decks, business cards, and even slides.
+
+## Features
+
+- Initialize a sample project and edit it instead of starting from scratch.
+
+- Include images, text, and different kinds of shapes.
+
+- Link any field to a column in the CSV file.
+
+- Position elements absolutely or relative to other elements, using anchors to simplify placement
+
+- Transform images using filters like crop, resize, rotate, or flip.
+
+- Build card images and export to PDF for printing.
+
+## Getting started
+
+To start creating decks, check out [Getting Started](DOCS.md/#getting-started).
+

decksmith-0.1.0/decksmith/card_builder.py

@@ -0,0 +1,607 @@
+"""
+This module contains the CardBuilder class,
+which is used to create card images based on a JSON specification.
+"""
+
+import operator
+import pandas as pd
+from PIL import Image, ImageDraw, ImageFont
+from .utils import get_wrapped_text, apply_anchor
+from .validate import validate_card
+
+
+class CardBuilder:
+    """
+    A class to build a card image based on a JSON specification.
+    Attributes:
+        spec (dict): The JSON specification for the card.
+        card (Image): The PIL Image object representing the card.
+        draw (ImageDraw): The PIL ImageDraw object for drawing on the card.
+    """
+
+    def __init__(self, spec: dict):
+        """
+        Initializes the CardBuilder with a JSON specification file.
+        Args:
+            spec_path (str): Path to the JSON specification file.
+        """
+        self.spec = spec
+        width = self.spec.get("width", 250)
+        height = self.spec.get("height", 350)
+        bg_color = tuple(self.spec.get("background_color", (255, 255, 255, 0)))
+        self.card = Image.new("RGBA", (width, height), bg_color)
+        self.draw = ImageDraw.Draw(self.card, "RGBA")
+        self.element_positions = {}
+
+    def _calculate_absolute_position(self, element: dict) -> tuple:
+        """
+        Calculates the absolute position of an element,
+        resolving relative positioning.
+        Args:
+            element (dict): The element dictionary.
+        Returns:
+            tuple: The absolute (x, y) position of the element.
+        """
+        # If the element has no 'relative_to', return its position directly
+        if "relative_to" not in element:
+            return tuple(element.get("position", [0, 0]))
+
+        # If the element has 'relative_to', resolve based on the reference element and anchor
+        relative_id, anchor = element["relative_to"]
+        if relative_id not in self.element_positions:
+            raise ValueError(
+                f"Element with id '{relative_id}' not found for relative positioning."
+            )
+
+        parent_bbox = self.element_positions[relative_id]
+        anchor_point = apply_anchor(parent_bbox, anchor)
+
+        offset = tuple(element.get("position", [0, 0]))
+        return tuple(map(operator.add, anchor_point, offset))
+
+    def _draw_text(self, element: dict):
+        """
+        Draws text on the card based on the provided element dictionary.
+        Args:
+            element (dict): A dictionary containing text properties such as
+                            'text', 'font_path', 'font_size', 'position',
+                            'color', and 'width'.
+        """
+        assert element.pop("type") == "text", "Element type must be 'text'"
+
+        # print(f"DEBUG: {element["text"]=}")
+
+        if pd.isna(element["text"]):
+            element["text"] = " "
+
+        # Convert font_path to a font object
+        font_size = element.pop("font_size", 10)
+        if font_path := element.pop("font_path", False):
+            element["font"] = ImageFont.truetype(
+                font_path,
+                font_size,
+                encoding="unic",
+            )
+        else:
+            element["font"] = ImageFont.load_default(font_size)
+
+        # Apply font_variant
+        if font_variant := element.pop("font_variant", None):
+            element["font"].set_variation_by_name(font_variant)
+
+        # Split text according to the specified width
+        if line_length := element.pop("width", False):
+            element["text"] = get_wrapped_text(
+                element["text"], element["font"], line_length
+            )
+
+        # Convert position and color to tuples
+        if position := element.pop("position", [0, 0]):
+            element["position"] = tuple(position)
+        if color := element.pop("color", [0, 0, 0]):
+            element["color"] = tuple(color)
+        if stroke_color := element.pop("stroke_color", None):
+            element["stroke_color"] = (
+                tuple(stroke_color) if stroke_color is not None else stroke_color
+            )
+
+        # Apply anchor manually (because PIL does not support anchor for multiline text)
+        original_pos = self._calculate_absolute_position(element)
+        element["position"] = original_pos
+
+        if "anchor" in element:
+            bbox = self.draw.textbbox(
+                xy=(0, 0),
+                text=element.get("text"),
+                font=element["font"],
+                spacing=element.get("line_spacing", 4),
+                align=element.get("align", "left"),
+                direction=element.get("direction", None),
+                features=element.get("features", None),
+                language=element.get("language", None),
+                stroke_width=element.get("stroke_width", 0),
+                embedded_color=element.get("embedded_color", False),
+            )
+            anchor_point = apply_anchor(bbox, element.pop("anchor"))
+            element["position"] = tuple(map(operator.sub, original_pos, anchor_point))
+
+        # Unpack the element dictionary and draw the text
+        self.draw.text(
+            xy=element.get("position"),
+            text=element.get("text"),
+            fill=element.get("color", None),
+            font=element["font"],
+            spacing=element.get("line_spacing", 4),
+            align=element.get("align", "left"),
+            direction=element.get("direction", None),
+            features=element.get("features", None),
+            language=element.get("language", None),
+            stroke_width=element.get("stroke_width", 0),
+            stroke_fill=element.get("stroke_color", None),
+            embedded_color=element.get("embedded_color", False),
+        )
+
+        # Store position if id is provided
+        if "id" in element:
+            bbox = self.draw.textbbox(
+                xy=element.get("position"),
+                text=element.get("text"),
+                font=element["font"],
+                spacing=element.get("line_spacing", 4),
+                align=element.get("align", "left"),
+                direction=element.get("direction", None),
+                features=element.get("features", None),
+                language=element.get("language", None),
+                stroke_width=element.get("stroke_width", 0),
+                embedded_color=element.get("embedded_color", False),
+            )
+            self.element_positions[element["id"]] = bbox
+
+    def _draw_image(self, element):
+        """
+        Draws an image on the card based on the provided element dictionary.
+        Args:
+            element (dict): A dictionary containing image properties such as
+                            'path', 'filters', and 'position'.
+        """
+        # Ensure the element type is 'image'
+        assert element.pop("type") == "image", "Element type must be 'image'"
+
+        # Load the image from the specified path
+        path = element["path"]
+        img = Image.open(path)
+
+        # Apply filters if specified
+        if "filters" in element:
+            for filter_name, filter_value in element["filters"].items():
+                if filter_name == "crop_top":
+                    if filter_value < 0:
+                        img = img.convert("RGBA")
+                        new_img = Image.new(
+                            "RGBA",
+                            (img.width, img.height - filter_value),
+                            (0, 0, 0, 0),
+                        )
+                        new_img.paste(img, (0, -filter_value))
+                        img = new_img
+                    else:
+                        img = img.crop((0, filter_value, img.width, img.height))
+                elif filter_name == "crop_bottom":
+                    if filter_value < 0:
+                        img = img.convert("RGBA")
+                        new_img = Image.new(
+                            "RGBA",
+                            (img.width, img.height - filter_value),
+                            (0, 0, 0, 0),
+                        )
+                        new_img.paste(img, (0, 0))
+                        img = new_img
+                    else:
+                        img = img.crop((0, 0, img.width, img.height - filter_value))
+                elif filter_name == "crop_left":
+                    if filter_value < 0:
+                        img = img.convert("RGBA")
+                        new_img = Image.new(
+                            "RGBA",
+                            (img.width - filter_value, img.height),
+                            (0, 0, 0, 0),
+                        )
+                        new_img.paste(img, (-filter_value, 0))
+                        img = new_img
+                    else:
+                        img = img.crop((filter_value, 0, img.width, img.height))
+                elif filter_name == "crop_right":
+                    if filter_value < 0:
+                        img = img.convert("RGBA")
+                        new_img = Image.new(
+                            "RGBA",
+                            (img.width - filter_value, img.height),
+                            (0, 0, 0, 0),
+                        )
+                        new_img.paste(img, (0, 0))
+                        img = new_img
+                    else:
+                        img = img.crop((0, 0, img.width - filter_value, img.height))
+                elif filter_name == "crop_box":
+                    img = img.convert("RGBA")
+                    x, y, w, h = filter_value
+                    new_img = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+                    src_x1 = max(0, x)
+                    src_y1 = max(0, y)
+                    src_x2 = min(img.width, x + w)
+                    src_y2 = min(img.height, y + h)
+                    if src_x1 < src_x2 and src_y1 < src_y2:
+                        src_w = src_x2 - src_x1
+                        src_h = src_y2 - src_y1
+                        src_img = img.crop(
+                            (src_x1, src_y1, src_x1 + src_w, src_y1 + src_h)
+                        )
+                        dst_x = src_x1 - x
+                        dst_y = src_y1 - y
+                        new_img.paste(src_img, (dst_x, dst_y))
+                    img = new_img
+                elif filter_name == "resize":
+                    new_width, new_height = filter_value
+                    if new_width is None and new_height is None:
+                        continue
+                    if new_width is None or new_height is None:
+                        original_width, original_height = img.size
+                        aspect_ratio = original_width / float(original_height)
+                        if new_width is None:
+                            new_width = int(new_height * aspect_ratio)
+                        else:  # new_height is None
+                            new_height = int(new_width / aspect_ratio)
+                    img = img.resize((new_width, new_height))
+                elif filter_name == "rotate":
+                    img = img.rotate(filter_value, expand=True)
+                elif filter_name == "flip":
+                    if filter_value == "horizontal":
+                        # pylint: disable=E1101
+                        img = img.transpose(Image.FLIP_LEFT_RIGHT)
+                    elif filter_value == "vertical":
+                        # pylint: disable=E1101
+                        img = img.transpose(Image.FLIP_TOP_BOTTOM)
+                else:
+                    raise ValueError(f"Unknown filter: {filter_name}")
+
+        # Convert position to a tuple
+        position = tuple(element.get("position", [0, 0]))
+
+        # Apply anchor if specified (because PIL does not support anchor for images)
+        position = self._calculate_absolute_position(element)
+        if "anchor" in element:
+            anchor_point = apply_anchor((img.width, img.height), element.pop("anchor"))
+            position = tuple(map(operator.sub, position, anchor_point))
+
+        # Paste the image onto the card at the specified position
+        if img.mode == "RGBA":
+            self.card.paste(img, position, mask=img)
+        else:
+            self.card.paste(img, position)
+
+        # Store position if id is provided
+        if "id" in element:
+            self.element_positions[element["id"]] = (
+                position[0],
+                position[1],
+                position[0] + img.width,
+                position[1] + img.height,
+            )
+
+    def _draw_shape_circle(self, element):
+        """
+        Draws a circle on the card based on the provided element dictionary.
+        Args:
+            element (dict): A dictionary containing circle properties such as
+                            'position', 'radius', 'color', 'outline', 'width', and 'anchor'.
+
+        Raises:
+            AssertionError: If the element type is not 'circle'.
+        """
+        assert element.pop("type") == "circle", "Element type must be 'circle'"
+
+        radius = element["radius"]
+        size = (radius * 2, radius * 2)
+
+        # Calculate absolute position for the element's anchor
+        absolute_pos = self._calculate_absolute_position(element)
+
+        # Convert color and outline to a tuple if specified
+        if "color" in element:
+            element["fill"] = tuple(element["color"])
+        if "outline_color" in element:
+            element["outline_color"] = tuple(element["outline_color"])
+
+        # Apply anchor if specified
+        if "anchor" in element:
+            # anchor_offset is the offset of the anchor from the top-left corner
+            anchor_offset = apply_anchor(size, element.pop("anchor"))
+            # top_left is the target position minus the anchor offset
+            absolute_pos = tuple(map(operator.sub, absolute_pos, anchor_offset))
+
+        # The center of the circle is the top-left position + radius
+        center_pos = (absolute_pos[0] + radius, absolute_pos[1] + radius)
+
+        # Draw the circle
+        self.draw.circle(
+            center_pos,
+            radius,
+            fill=element.get("fill", None),
+            outline=element.get("outline_color", None),
+            width=element.get("outline_width", 1),
+        )
+
+        # Store position if id is provided
+        if "id" in element:
+            # The stored bbox is based on the top-left position
+            self.element_positions[element["id"]] = (
+                absolute_pos[0],
+                absolute_pos[1],
+                absolute_pos[0] + size[0],
+                absolute_pos[1] + size[1],
+            )
+
+    def _draw_shape_ellipse(self, element):
+        """
+        Draws an ellipse on the card based on the provided element dictionary.
+
+        Args:
+            element (dict): A dictionary containing ellipse properties such as
+                            'position', 'size', 'color', 'outline', 'width', and 'anchor'.
+
+        Raises:
+            AssertionError: If the element type is not 'ellipse'.
+        """
+        assert element.pop("type") == "ellipse", "Element type must be 'ellipse'"
+
+        # Get size
+        size = element["size"]
+
+        # Calculate absolute position
+        position = self._calculate_absolute_position(element)
+
+        # Convert color and outline to a tuple if specified
+        if "color" in element:
+            element["fill"] = tuple(element["color"])
+        if "outline_color" in element:
+            element["outline_color"] = tuple(element["outline_color"])
+
+        # Apply anchor if specified
+        if "anchor" in element:
+            # For anchoring, we need an offset from the top-left corner.
+            # We calculate this offset based on the element's size.
+            anchor_offset = apply_anchor(size, element.pop("anchor"))
+            # We subtract the offset from the calculated absolute position
+            # to get the top-left corner of the bounding box.
+            position = tuple(map(operator.sub, position, anchor_offset))
+
+        # Compute bounding box from the final position and size
+        bounding_box = (
+            position[0],
+            position[1],
+            position[0] + size[0],
+            position[1] + size[1],
+        )
+
+        # Draw the ellipse
+        self.draw.ellipse(
+            bounding_box,
+            fill=element.get("fill", None),
+            outline=element.get("outline_color", None),
+            width=element.get("outline_width", 1),
+        )
+
+        # Store position if id is provided
+        if "id" in element:
+            self.element_positions[element["id"]] = bounding_box
+
+    def _draw_shape_polygon(self, element):
+        """
+        Draws a polygon on the card based on the provided element dictionary.
+        Args:
+            element (dict): A dictionary containing polygon properties such as
+                            'position', 'points', 'color', 'outline', 'width', and 'anchor'.
+        Raises:
+            AssertionError: If the element type is not 'polygon'.
+        """
+        assert element.pop("type") == "polygon", "Element type must be 'polygon'"
+
+        # Get points and convert to tuples
+        points = element.get("points", [])
+        if not points:
+            return
+        points = [tuple(p) for p in points]
+
+        # Compute bounding box relative to (0,0)
+        min_x = min(p[0] for p in points)
+        max_x = max(p[0] for p in points)
+        min_y = min(p[1] for p in points)
+        max_y = max(p[1] for p in points)
+        bounding_box = (min_x, min_y, max_x, max_y)
+
+        # Calculate absolute position for the element's anchor
+        absolute_pos = self._calculate_absolute_position(element)
+
+        # Convert color and outline to a tuple if specified
+        if "color" in element:
+            element["fill"] = tuple(element["color"])
+        if "outline_color" in element:
+            element["outline_color"] = tuple(element["outline_color"])
+
+        # This will be the top-left offset for the points
+        offset = absolute_pos
+
+        # Apply anchor if specified
+        if "anchor" in element:
+            # anchor_point is the coordinate of the anchor within the relative bbox
+            anchor_point = apply_anchor(bounding_box, element.pop("anchor"))
+            # The final offset is the target position minus the anchor point's relative coord
+            offset = tuple(map(operator.sub, absolute_pos, anchor_point))
+
+        # Translate points by the final offset
+        final_points = [(p[0] + offset[0], p[1] + offset[1]) for p in points]
+
+        # Draw the polygon
+        self.draw.polygon(
+            final_points,
+            fill=element.get("fill", None),
+            outline=element.get("outline_color", None),
+            width=element.get("outline_width", 1),
+        )
+
+        # Store position if id is provided
+        if "id" in element:
+            # The stored bbox is the relative bbox translated by the offset
+            self.element_positions[element["id"]] = (
+                min_x + offset[0],
+                min_y + offset[1],
+                max_x + offset[0],
+                max_y + offset[1],
+            )
+
+    def _draw_shape_regular_polygon(self, element):
+        """
+        Draws a regular polygon on the card based on the provided element dictionary.
+
+        Args:
+            element (dict): A dictionary containing regular polygon properties such as
+                            'position', 'radius', 'sides', 'rotation', 'color', 'outline',
+                            'width', and 'anchor'.
+
+        Raises:
+            AssertionError: If the element type is not 'regular-polygon'.
+        """
+        assert (
+            element.pop("type") == "regular-polygon"
+        ), "Element type must be 'regular-polygon'"
+
+        radius = element["radius"]
+        size = (radius * 2, radius * 2)
+
+        # Calculate absolute position for the element's anchor
+        absolute_pos = self._calculate_absolute_position(element)
+
+        # Convert color and outline to a tuple if specified
+        if "color" in element:
+            element["fill"] = tuple(element["color"])
+        if "outline_color" in element:
+            element["outline_color"] = tuple(element["outline_color"])
+
+        # Apply anchor if specified
+        if "anchor" in element:
+            # anchor_offset is the offset of the anchor from the top-left corner
+            anchor_offset = apply_anchor(size, element.pop("anchor"))
+            # top_left is the target position minus the anchor offset
+            absolute_pos = tuple(map(operator.sub, absolute_pos, anchor_offset))
+
+        # The center of the polygon is the top-left position + radius
+        center_pos = (absolute_pos[0] + radius, absolute_pos[1] + radius)
+
+        # Draw the regular polygon
+        self.draw.regular_polygon(
+            (center_pos[0], center_pos[1], radius),
+            n_sides=element["sides"],
+            rotation=element.get("rotation", 0),
+            fill=element.get("fill", None),
+            outline=element.get("outline_color", None),
+            width=element.get("outline_width", 1),
+        )
+
+        # Store position if id is provided
+        if "id" in element:
+            # The stored bbox is based on the top-left position
+            self.element_positions[element["id"]] = (
+                absolute_pos[0],
+                absolute_pos[1],
+                absolute_pos[0] + size[0],
+                absolute_pos[1] + size[1],
+            )
+
+    def _draw_shape_rectangle(self, element):
+        """
+        Draws a rectangle on the card based on the provided element dictionary.
+
+        Args:
+            element (dict): A dictionary containing rectangle properties such as
+                            'size', 'color', 'outline_color', 'width', 'radius',
+                            'corners', 'position', and 'anchor'.
+        Raises:
+            AssertionError: If the element type is not 'rectangle'.
+        """
+        assert element.pop("type") == "rectangle", "Element type must be 'rectangle'"
+
+        # print(f"DEBUG: {element=}")
+
+        # Get size
+        size = element["size"]
+
+        # Calculate absolute position
+        position = self._calculate_absolute_position(element)
+
+        # Convert color, outline and corners to a tuple if specified
+        if "color" in element:
+            element["fill"] = tuple(element["color"])
+        if "outline_color" in element:
+            element["outline_color"] = tuple(element["outline_color"])
+        if "corners" in element:
+            element["corners"] = tuple(element["corners"])
+
+        # Apply anchor if specified
+        if "anchor" in element:
+            # For anchoring, we need an offset from the top-left corner.
+            # We calculate this offset based on the element's size.
+            anchor_offset = apply_anchor(size, element.pop("anchor"))
+            # We subtract the offset from the calculated absolute position
+            # to get the top-left corner of the bounding box.
+            position = tuple(map(operator.sub, position, anchor_offset))
+
+        # Compute bounding box from the final position and size
+        bounding_box = (
+            position[0],
+            position[1],
+            position[0] + size[0],
+            position[1] + size[1],
+        )
+
+        # print(f"DEBUG: Transformed {element=}")
+
+        # Draw the rectangle
+        self.draw.rounded_rectangle(
+            bounding_box,
+            radius=element.get("corner_radius", 0),
+            fill=element.get("fill", None),
+            outline=element.get("outline_color", None),
+            width=element.get("outline_width", 1),
+            corners=element.get("corners", None),
+        )
+
+        # Store position if id is provided
+        if "id" in element:
+            self.element_positions[element["id"]] = bounding_box
+
+    def build(self, output_path):
+        """
+        Builds the card image by drawing all elements specified in the JSON.
+        Args:
+            output_path (str): The path where the card image will be saved.
+        """
+        validate_card(self.spec)
+
+        for el in self.spec.get("elements", []):
+            el_type = el.get("type")
+            if el_type == "text":
+                self._draw_text(el)
+            elif el_type == "image":
+                self._draw_image(el)
+            elif el_type == "circle":
+                self._draw_shape_circle(el)
+            elif el_type == "ellipse":
+                self._draw_shape_ellipse(el)
+            elif el_type == "polygon":
+                self._draw_shape_polygon(el)
+            elif el_type == "regular-polygon":
+                self._draw_shape_regular_polygon(el)
+            elif el_type == "rectangle":
+                self._draw_shape_rectangle(el)
+        self.card.save(output_path)
+        print(f"(✔) Card saved to {output_path}")

decksmith-0.1.0/decksmith/deck_builder.py

@@ -0,0 +1,94 @@
+"""
+This module contains the DeckBuilder class,
+which is used to create a deck of cards based on a JSON specification
+and a CSV file.
+"""
+
+import concurrent.futures
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from .card_builder import CardBuilder
+
+
+class DeckBuilder:
+    """
+    A class to build a deck of cards based on a JSON specification and a CSV file.
+    Attributes:
+        spec_path (str): Path to the JSON specification file.
+        csv_path (str): Path to the CSV file containing card data.
+        cards (list): List of CardBuilder instances for each card in the deck.
+    """
+
+    def __init__(self, spec_path: str, csv_path: str = None):
+        """
+        Initializes the DeckBuilder with a JSON specification file and a CSV file.
+        Args:
+            spec_path (str): Path to the JSON specification file.
+            csv_path (str): Path to the CSV file containing card data.
+        """
+        self.spec_path = spec_path
+        self.csv_path = csv_path
+        self.cards = []
+
+    def _replace_macros(self, row: dict) -> dict:
+        """
+        Replaces %colname% macros in the card specification with values from the row.
+        Works recursively for nested structures.
+        Args:
+            row (dict): A dictionary representing a row from the CSV file.
+        Returns:
+            dict: The updated card specification with macros replaced.
+        """
+
+        def replace_in_value(value):
+            if isinstance(value, str):
+                stripped_value = value.strip()
+                # First, check for an exact macro match to preserve type
+                for key in row:
+                    if stripped_value == f"%{key}%":
+                        return row[key]  # Return the raw value, preserving type
+
+                # If no exact match, perform standard string replacement for all macros
+                for key, val in row.items():
+                    value = value.replace(f"%{key}%", str(val))
+                return value
+
+            if isinstance(value, list):
+                return [replace_in_value(v) for v in value]
+
+            if isinstance(value, dict):
+                return {k: replace_in_value(v) for k, v in value.items()}
+
+            return value
+
+        with open(self.spec_path, "r", encoding="utf-8") as f:
+            spec = json.load(f)
+        return replace_in_value(spec)
+
+    def build_deck(self, output_path: str):
+        """
+        Builds the deck of cards by reading the CSV file and creating CardBuilder instances.
+        """
+        if not self.csv_path:
+            with open(self.spec_path, "r", encoding="utf-8") as f:
+                spec = json.load(f)
+            card_builder = CardBuilder(spec)
+            card_builder.build(Path(output_path) / "card_1.png")
+            return
+
+        df = pd.read_csv(self.csv_path, encoding="utf-8", sep=";", header=0)
+
+        def build_card(row_tuple):
+            idx, row = row_tuple
+            spec = self._replace_macros(row.to_dict())
+            card_builder = CardBuilder(spec)
+            card_builder.build(Path(output_path) / f"card_{idx + 1}.png")
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            list(executor.map(build_card, df.iterrows()))
+
+        # for row_tuple in df.iterrows():
+        #     build_card(row_tuple)

decksmith-0.1.0/decksmith/export.py

@@ -0,0 +1,177 @@
+"""
+This module provides the functionality to export images from a folder to a PDF file.
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Tuple
+
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import mm
+from reportlab.pdfgen import canvas
+
+
+class PdfExporter:
+    """
+    A class to export images from a folder to a PDF file.
+
+    Attributes:
+        image_folder (Path): The folder containing the images to be exported.
+        image_paths (List[str]): A list of paths to the images to be exported.
+        output_path (str): The path to the output PDF file.
+        page_size (Tuple[float, float]): The size of the PDF pages.
+        image_width (float): The width of the images in mm.
+        image_height (float): The height of the images in mm.
+        gap (float): The gap between images in pixels.
+        margins (Tuple[float, float]): The horizontal and vertical margins of the pages.
+    """
+
+    def __init__(
+        self,
+        image_folder: str,
+        output_path: str,
+        page_size_str: str = "A4",
+        image_width: float = 63,
+        image_height: float = 88,
+        gap: float = 0,
+        margins: Tuple[float, float] = (2, 2),
+    ):
+        self.image_folder = Path(image_folder)
+        self.image_paths = self._get_image_paths()
+        self.output_path = output_path
+        self.page_size = self._get_page_size(page_size_str)
+        self.image_width = image_width * mm
+        self.image_height = image_height * mm
+        self.gap = gap * mm
+        self.margins = (margins[0] * mm, margins[1] * mm)
+        self.pdf = canvas.Canvas(self.output_path, pagesize=self.page_size)
+
+    def _get_image_paths(self) -> List[str]:
+        """
+        Scans the image folder and returns a list of image paths.
+
+        Returns:
+            List[str]: A sorted list of image paths.
+        """
+        image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+        image_paths = []
+        for file_path in self.image_folder.iterdir():
+            if file_path.suffix.lower() in image_extensions:
+                image_paths.append(str(file_path))
+        return sorted(image_paths)
+
+    def _get_page_size(self, page_size_str: str) -> Tuple[float, float]:
+        """
+        Returns the page size from a string.
+
+        Args:
+            page_size_str (str): The string representing the page size.
+
+        Returns:
+            Tuple[float, float]: The page size in points.
+        """
+        if page_size_str.lower() == "a4":
+            return A4
+        # Add other page sizes here if needed
+        return A4
+
+    def _calculate_layout(self, page_width: float, page_height: float):
+        """
+        Calculates the optimal layout for the images on the page.
+
+        Args:
+            page_width (float): The width of the page.
+            page_height (float): The height of the page.
+
+        Returns:
+            Tuple[int, int, bool]: The number of columns, rows, and if the layout is rotated.
+        """
+        best_fit = 0
+        best_layout = (0, 0, False)
+
+        for rotated in [False, True]:
+            img_w, img_h = (
+                (self.image_width, self.image_height)
+                if not rotated
+                else (self.image_height, self.image_width)
+            )
+
+            cols = int(
+                (page_width - 2 * self.margins[0] + self.gap) / (img_w + self.gap)
+            )
+            rows = int(
+                (page_height - 2 * self.margins[1] + self.gap) / (img_h + self.gap)
+            )
+
+            if cols * rows > best_fit:
+                best_fit = cols * rows
+                best_layout = (cols, rows, rotated)
+
+        return best_layout
+
+    def export(self):
+        """
+        Exports the images to a PDF file.
+        """
+        try:
+            page_width, page_height = self.page_size
+            cols, rows, rotated = self._calculate_layout(page_width, page_height)
+
+            if cols == 0 or rows == 0:
+                logging.error("The images are too large to fit on the page.")
+                return
+
+            img_w, img_h = (
+                (self.image_width, self.image_height)
+                if not rotated
+                else (self.image_height, self.image_width)
+            )
+
+            total_width = cols * img_w + (cols - 1) * self.gap
+            total_height = rows * img_h + (rows - 1) * self.gap
+            start_x = (page_width - total_width) / 2
+            start_y = (page_height - total_height) / 2
+
+            images_on_page = 0
+            for image_path in self.image_paths:
+                if images_on_page == cols * rows:
+                    self.pdf.showPage()
+                    images_on_page = 0
+
+                row = images_on_page // cols
+                col = images_on_page % cols
+
+                x = start_x + col * (img_w + self.gap)
+                y = start_y + row * (img_h + self.gap)
+
+                if not rotated:
+                    self.pdf.drawImage(
+                        image_path,
+                        x,
+                        y,
+                        width=img_w,
+                        height=img_h,
+                        preserveAspectRatio=True,
+                    )
+                else:
+                    self.pdf.saveState()
+                    center_x = x + img_w / 2
+                    center_y = y + img_h / 2
+                    self.pdf.translate(center_x, center_y)
+                    self.pdf.rotate(90)
+                    self.pdf.drawImage(
+                        image_path,
+                        -img_h / 2,
+                        -img_w / 2,
+                        width=img_h,
+                        height=img_w,
+                        preserveAspectRatio=True,
+                    )
+                    self.pdf.restoreState()
+                images_on_page += 1
+
+            self.pdf.save()
+            logging.info("Successfully exported PDF to %s", self.output_path)
+        except Exception as e:
+            logging.error("An error occurred during PDF export: %s", e)
+            raise

decksmith-0.1.0/decksmith/main.py

@@ -0,0 +1,104 @@
+"""
+This module provides a command-line tool for building decks of cards.
+"""
+
+import os
+import shutil
+from importlib import resources
+
+import traceback
+
+import click
+from decksmith.deck_builder import DeckBuilder
+from decksmith.export import PdfExporter
+
+
+@click.group()
+def cli():
+    """A command-line tool for building decks of cards."""
+
+
+@cli.command()
+def init():
+    """Initializes a new project by creating deck.json and deck.csv."""
+    if os.path.exists("deck.json") or os.path.exists("deck.csv"):
+        click.echo("(!) Project already initialized.")
+        return
+
+    with resources.path("templates", "deck.json") as template_path:
+        shutil.copy(template_path, "deck.json")
+    with resources.path("templates", "deck.csv") as template_path:
+        shutil.copy(template_path, "deck.csv")
+
+    click.echo("(✔) Initialized new project from templates.")
+
+
+@cli.command()
+@click.option("--output", default="output", help="The output directory for the deck.")
+@click.option(
+    "--spec", default="deck.json", help="The path to the deck specification file."
+)
+@click.option("--data", default="deck.csv", help="The path to the data file.")
+def build(output, spec, data):
+    """Builds the deck of cards."""
+    if not os.path.exists(output):
+        os.makedirs(output)
+
+    click.echo(f"(i) Building deck in {output}...")
+    try:
+        builder = DeckBuilder(spec, data)
+        builder.build_deck(output)
+    # pylint: disable=W0718
+    except Exception as exc:
+        with open("log.txt", "w", encoding="utf-8") as log:
+            log.write(traceback.format_exc())
+        # print(f"{traceback.format_exc()}", end="\n")
+        print(f"(x) Error building deck '{data}' from spec '{spec}':")
+        print(" " * 4 + f"{exc}")
+        return
+
+    click.echo("(✔) Deck built successfully.")
+
+
+@cli.command()
+@click.argument("image_folder")
+@click.option("--output", default="output.pdf", help="The output PDF file path.")
+@click.option("--page-size", default="A4", help="The page size (e.g., A4).")
+@click.option(
+    "--width", type=float, default=63.5, help="The width of the images in mm."
+)
+@click.option(
+    "--height", type=float, default=88.9, help="The height of the images in mm."
+)
+@click.option("--gap", type=float, default=0, help="The gap between images in pixels.")
+@click.option(
+    "--margins",
+    type=float,
+    nargs=2,
+    default=[2, 2],
+    help="The horizontal and vertical margins in mm.",
+)
+def export(image_folder, output, page_size, width, height, gap, margins):
+    """Exports images from a folder to a PDF file."""
+    try:
+        exporter = PdfExporter(
+            image_folder=image_folder,
+            output_path=output,
+            page_size_str=page_size,
+            image_width=width,
+            image_height=height,
+            gap=gap,
+            margins=margins,
+        )
+        exporter.export()
+        click.echo(f"(✔) Successfully exported PDF to {output}")
+    # pylint: disable=W0718
+    except Exception as exc:
+        with open("log.txt", "w", encoding="utf-8") as log:
+            log.write(traceback.format_exc())
+        print(f"(x) Error exporting images to '{output}':")
+        print(" " * 4 + f"{exc}")
+
+
+if __name__ == "__main__":
+    cli()

decksmith-0.1.0/decksmith/utils.py

@@ -0,0 +1,83 @@
+"""
+This module provides utility functions for text wrapping and positioning.
+"""
+
+from PIL import ImageFont
+
+
+def get_wrapped_text(text: str, font: ImageFont.ImageFont, line_length: int):
+    """
+    Wraps text to fit within a specified line length using the given font.
+    Args:
+        text (str): The text to wrap.
+        font (ImageFont.ImageFont): The font to use for measuring text length.
+        line_length (int): The maximum length of each line in pixels.
+
+    Returns:
+        str: The wrapped text with newlines inserted where necessary.
+    """
+    lines = [""]
+    for word in text.split():
+        line = f"{lines[-1]} {word}".strip()
+        if font.getlength(line) <= line_length:
+            lines[-1] = line
+        else:
+            lines.append(word)
+    return "\n".join(lines)
+
+
+def apply_anchor(size: tuple, anchor: str):
+    """
+    Applies an anchor to a size tuple to determine the position of an element.
+    Args:
+        size (tuple): A tuple representing the size (width, height).
+        anchor (str): The anchor position, e.g., "center", "top-left",
+                      "top-right", "bottom-left", "bottom-right".
+    Returns:
+        tuple: A tuple representing the position (x, y) based on the anchor.
+    """
+    if len(size) == 2:
+        x, y = size
+        if anchor == "top-left":
+            return (0, 0)
+        if anchor == "top-center":
+            return (x // 2, 0)
+        if anchor == "top-right":
+            return (x, 0)
+        if anchor == "middle-left":
+            return (0, y // 2)
+        if anchor == "center":
+            return (x // 2, y // 2)
+        if anchor == "middle-right":
+            return (x, y // 2)
+        if anchor == "bottom-left":
+            return (0, y)
+        if anchor == "bottom-center":
+            return (x // 2, y)
+        if anchor == "bottom-right":
+            return (x, y)
+        raise ValueError(f"Unknown anchor: {anchor}")
+    if len(size) == 4:
+        x1, y1, x2, y2 = size
+        width = x2 - x1
+        height = y2 - y1
+        if anchor == "top-left":
+            return (x1, y1)
+        if anchor == "top-center":
+            return (x1 + width // 2, y1)
+        if anchor == "top-right":
+            return (x2, y1)
+        if anchor == "middle-left":
+            return (x1, y1 + height // 2)
+        if anchor == "center":
+            return (x1 + width // 2, y1 + height // 2)
+        if anchor == "middle-right":
+            return (x2, y1 + height // 2)
+        if anchor == "bottom-left":
+            return (x1, y2)
+        if anchor == "bottom-center":
+            return (x1 + width // 2, y2)
+        if anchor == "bottom-right":
+            return (x2, y2)
+        raise ValueError(f"Unknown anchor: {anchor}")
+    return None

decksmith-0.1.0/decksmith/validate.py

@@ -0,0 +1,108 @@
+"""
+Python module for validating a dictionar
+"""
+
+from jval import validate
+
+ELEMENT_SPEC = {
+    "?*id": "<str>",
+    "*type": "<str>",
+    "?*position": ["<float>"],
+    "?*relative_to": ["<str>"],
+    "?*anchor": "<str>",
+}
+
+SPECS_FOR_TYPE = {
+    "text": {
+        "*text": "<str>",
+        "?*color": ["<int>"],
+        "?*font_path": "<str>",
+        "?*font_size": "<int>",
+        "?*font_variant": "<str>",
+        "?*line_spacing": "<int>",
+        "?*width": "<int>",
+        "?*align": "<str>",
+        "?*stroke_width": "<int>",
+        "?*stroke_color": ["<int>"],
+    },
+    "image": {
+        "*path": "<str>",
+        "?*filters": {
+            "?*crop_top": "<int>",
+            "?*crop_bottom": "<int>",
+            "?*crop_left": "<int>",
+            "?*crop_right": "<int>",
+            "?*crop_box": ["<int>"],
+            "?*rotate": "<int>",
+            "?*flip": "<str>",
+            "?*resize": ["<?int>"],
+        },
+    },
+    "circle": {
+        "*radius": "<int>",
+        "?*color": ["<int>"],
+        "?*outline_color": ["<int>"],
+        "?*outline_width": "<int>",
+    },
+    "ellipse": {
+        "*size": ["<int>"],
+        "?*color": ["<int>"],
+        "?*outline_color": ["<int>"],
+        "?*outline_width": "<int>",
+    },
+    "polygon": {
+        "*points": [["<int>"]],
+        "?*color": ["<int>"],
+        "?*outline_color": ["<int>"],
+        "?*outline_width": "<int>",
+    },
+    "regular-polygon": {
+        "*radius": "<int>",
+        "*sides": "<int>",
+        "?*rotation": "<int>",
+        "?*color": ["<int>"],
+        "?*outline_color": ["<int>"],
+        "?*outline_width": "<int>",
+    },
+    "rectangle": {
+        "*size": ["<int>"],
+        "?*corners": ["<bool>"],
+        "?*corner_radius": "<int>",
+        "?*color": ["<int>"],
+        "?*outline_color": ["<int>"],
+        "?*outline_width": "<int>",
+    },
+}
+
+CARD_SPEC = {
+    "*width": "<int>",
+    "*height": "<int>",
+    "?*background_color": ["<int>"],
+    "*elements": [],
+}
+
+
+def validate_element(element, element_type):
+    """
+    Validates an element of a card against a spec, raising an exception
+    if it does not meet the spec.
+    Args:
+        element (dict): The card element.
+        element_type (str): The type of the element
+    """
+    spec = ELEMENT_SPEC | SPECS_FOR_TYPE[element_type]
+    validate(element, spec)
+
+
+def validate_card(card):
+    """
+    Validates a card against a spec, raising an exception
+    if it does not meet the spec.
+    Args:
+        card (dict): The card.
+    """
+    # print(f"DEBUG:\n{card=}")
+    validate(card, CARD_SPEC)
+    for element in card["elements"]:
+        # print(f"DEBUG: {element['type']}")
+        validate_element(element, element["type"])

decksmith-0.1.0/docs/README.md

@@ -0,0 +1,23 @@
+# DeckSmith
+
+A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck.
+
+DeckSmith is ideal for automating the creation of all kinds of decks, including TCG decks, tarot decks, business cards, and even slides.
+
+## Features
+
+- Initialize a sample project and edit it instead of starting from scratch.
+
+- Include images, text, and different kinds of shapes.
+
+- Link any field to a column in the CSV file.
+
+- Position elements absolutely or relative to other elements, using anchors to simplify placement
+
+- Transform images using filters like crop, resize, rotate, or flip.
+
+- Build card images and export to PDF for printing.
+
+## Getting started
+
+To start creating decks, check out [Getting Started](DOCS.md/#getting-started).

decksmith-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "decksmith"
+version = "0.1.0"
+description = "A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck."
+authors = [
+    {name = "Julio Cabria", email = "juliocabria@tutanota.com"},
+]
+license = "GPL-2.0-only"
+readme = "docs/README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "click",
+    "jval==1.0.6",
+    "pandas",
+    "pillow>=11.3.0",
+    "reportlab>=4.4.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "poetry",
+]
+
+[tool.poetry]
+name = "decksmith"
+version = "0.1.0"
+description = "A command-line application to dynamically generate decks of cards from a JSON specification and a CSV data file, inspired by nandeck."
+authors = ["Julio Cabria <juliocabria@tutanota.com>"]
+license = "GPL-2.0-only"
+readme = "docs/README.md"
+homepage = "https://github.com/Julynx/decksmith"
+
+[tool.poetry.dependencies]
+python = ">=3.13"
+click = "*"
+jval = "1.0.6"
+pandas = "*"
+pillow = ">=11.3.0"
+reportlab = ">=4.4.3"
+
+[tool.poetry.scripts]
+decksmith = "decksmith.main:cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["decksmith*", "test*"]
+namespaces = false
+
+[tool.setuptools.package-data]
+decksmith = ["../templates/*"]
+
+[project.scripts]
+decksmith = "decksmith.main:cli"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"