Photo-Composition-Designer 1.0.1__tar.gz → 1.0.2__tar.gz

photo_composition_designer-1.0.2/AGENTS.md

@@ -0,0 +1,94 @@
+# Agent Guidelines for Python Code Quality
+
+This document provides guidelines for maintaining high-quality Python code. These rules MUST be followed by all AI coding agents and contributors.
+
+## Your Core Principles
+
+All code you write MUST be fully optimized.
+
+"Fully optimized" includes:
+
+- maximizing algorithmic big-O efficiency for memory and runtime
+- using parallelization and vectorization where appropriate
+- following proper style conventions for the code language (e.g. maximizing code reuse (DRY))
+
+## Preferred Tools
+
+- Use `uv` for Python package management and to create a `.venv` if it is not present.
+
+## Code Style and Formatting
+
+- **MUST** use meaningful, descriptive variable and function names
+- **MUST** follow PEP 8 style guidelines
+- **MUST** use 4 spaces for indentation (never tabs)
+- **NEVER** use emoji, or unicode that emulates emoji (e.g. ✓, ✗). The only exception is when writing tests and testing the impact of multibyte characters.
+- Use snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
+- Limit line length to 100 characters (ruff formatter standard)
+- **MUST** avoid including redundant comments which are tautological or self-demonstating (e.g. cases where it is easily parsable what the code does at a glance so the comment does)
+- **MUST** avoid including comments which leak what this file contains, or leak the original user prompt, ESPECIALLY if it's irrelevant to the output code.
+
+## Documentation
+
+- **MUST** include docstrings for all public functions, classes, and methods
+- **MUST** document function parameters, return values, and exceptions raised
+- Keep comments up-to-date with code changes
+
+## Type Hints
+
+- **MUST** use type hints for all function signatures (parameters and return values)
+- **NEVER** use `Any` type unless absolutely necessary
+- **MUST** run mypy and resolve all type errors
+- Use `Optional[T]` or `T | None` for nullable types
+
+## Error Handling
+
+- **NEVER** silently swallow exceptions without logging
+- **MUST** never use bare `except:` clauses
+- **MUST** catch specific exceptions rather than broad exception types
+- **MUST** use context managers (`with` statements) for resource cleanup
+- Provide meaningful error messages
+
+## Function Design
+
+- **MUST** keep functions focused on a single responsibility
+- **NEVER** use mutable objects (lists, dicts) as default argument values
+- Limit function parameters to 5 or fewer
+- Return early to reduce nesting
+
+## Class Design
+
+- **MUST** keep classes focused on a single responsibility
+- **MUST** keep `__init__` simple; avoid complex logic
+- Use dataclasses for simple data containers
+- Prefer composition over inheritance
+
+## Testing
+
+- **MUST** write unit tests for all new functions and classes
+- **MUST** mock external dependencies (APIs, databases, file systems)
+- **MUST** use pytest as the testing framework
+
+## Imports and Dependencies
+
+- **MUST** avoid wildcard imports (`from module import *`)
+- **MUST** document dependencies in `pyproject.toml`
+- Use `uv` for fast package management and dependency resolution
+
+## Python Best Practices
+
+- **NEVER** use mutable default arguments
+- **MUST** use context managers (`with` statement) for file/resource management
+- **MUST** use `is` for comparing with `None`, `True`, `False`
+- **MUST** use f-strings for string formatting
+- Use list comprehensions and generator expressions
+- Use `enumerate()` instead of manual counter variables
+
+## Before Committing
+
+- [ ] Code formatter pass: >> make format
+- [ ] Linter pass: >> make lint
+- [ ] All tests pass: >> make test
+
+---
+
+**Remember:** Prioritize clarity and maintainability over cleverness. This is your core directive.

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/HISTORY.md

@@ -4,6 +4,49 @@ Changelog
 
 (unreleased)
 ------------
+- Improve layouting: distribute 2x2 images more equally. Use image
+  importance weight where useful. Consider object area when calculating
+  importance. Clear cache at session start. [Paul Magister]
+- No more workspace.xml in vcs. [Paul Magister]
+- Calculate image weights better. [Paul Magister]
+- Calculate image weights better. [Paul Magister]
+- Improve reactivity: add file cache to store image recognition data.
+  [Paul Magister]
+- Improve reactivity: render preview only as large as needed. [Paul
+  Magister]
+- Update config-cli-gui: improved gui handling, reload last config.yaml,
+  move AppConfig into general base class. [Paul Magister]
+- Use ttkbootstrap for modern gui design. [Paul Magister]
+- CollageRenderer.py: imageScoreFactor: Factor how much the objects
+  (humans, animals, ...) in the image are considered for weighting the
+  image size. [Paul Magister]
+- CollageRenderer.py: add rounded corner functionality: add parameter.
+  [Paul Magister]
+- CollageRenderer.py: add rounded corner functionality. [Paul Magister]
+- CollageRenderer.py: improve tests, more variants, shorter P and L for
+  portrait and landscape. Overweight portraits in one row so that they
+  get more space. [Paul Magister]
+- Adjust weight in SmartCrop. [Paul Magister]
+- Code formatting and import optimization. [Paul Magister]
+- Algorithm finally working. [Paul Magister]
+- Draft: spezielle Behandlung für 3: fast perfekt: fix gap bug. [Paul
+  Magister]
+- Draft: spezielle Behandlung für 3: fast perfekt. [Paul Magister]
+- Draft: spezielle Behandlung für 3. [Paul Magister]
+- Draft: neues arrangement mit fitting algo: schon viel besser, aber bei
+  3 Bildern geht es nicht. [Paul Magister]
+- Draft: neues arrangement mit fitting algo: schon viel besser, aber bei
+  3 Bildern geht es nicht. [Paul Magister]
+- Draft: neues arrangement mit fitting algo. [Paul Magister]
+- Make pytree: improvements on show_tree.py: doc external tool. [Paul
+  Magister]
+- Improve cropping boxes and test visualization. [Paul Magister]
+- CollageRenderer.py: rename private methods. [Paul Magister]
+
+
+1.0.1 (2026-06-14)
+------------------
+- Docs: Update HISTORY.md for release 1.0.1. [Paul Magister]
 - Object recognition: improve cropping: prevent crash on None. [Paul
   Magister]
 - Object recognition: improve cropping. [Paul Magister]

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/LICENSE

@@ -22,3 +22,32 @@ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 
 For more information, please refer to <https://unlicense.org>
+
+----------
+
+CollageRenderer.py:
+Parts of the Collage Algorithm is adapted from
+PyPhotoCollage/PhotoCollage.py
+Thanks to Tim Wilson
+
+MIT License
+
+Copyright (c) 2020 Tim Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{photo_composition_designer-1.0.1/src/Photo_Composition_Designer.egg-info → photo_composition_designer-1.0.2}/PKG-INFO

@@ -1,13 +1,14 @@
 Metadata-Version: 2.4
 Name: Photo-Composition-Designer
-Version: 1.0.1
+Version: 1.0.2
 Summary: Feature-rich Python project template for Photo-Composition-Designer.
 Author: pamagister
 Requires-Python: <4.0,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: astral>=3.2
-Requires-Dist: config-cli-gui>=0.3.2
+Requires-Dist: config-cli-gui>=0.3.5
+Requires-Dist: ttkbootstrap>=1.20.3
 Requires-Dist: exifread>=3.5.1
 Requires-Dist: geopandas>=1.1.1
 Requires-Dist: holidays>=0.84

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/config.yaml

@@ -1,6 +1,16 @@
 app:
+  # Date format to use | type=str
+  date_format: '%Y-%m-%d'
   # Logging level for the application | type=str | choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
   log_level: INFO
+  # Maximum log file size in MB before rotation | type=int
+  log_file_max_size: 2
+  # Enable logging to file | type=bool | choices=[True, False]
+  enable_file_logging: true
+  # Enable logging to console | type=bool | choices=[True, False]
+  enable_console_logging: true
+  # GUI theme setting supported by ttkbootstrap | type=str | choices=['cosmo', 'flatly', 'litera', 'minty', 'lumen', 'sandstone', 'yeti', 'pulse', 'united', 'darkly', 'superhero', 'solar', 'cyborg', 'vapor', 'simplex']
+  theme: darkly
 general:
   # Path to the directory containing photos (absolute, or relative to this config.ini file) | type=PosixPath | [CLI]
   photoDirectory: images
@@ -61,6 +71,10 @@ layout:
   marginSides: 3
   # Spacing between elements in mm | type=int
   spacing: 2
+  # Use rounded corners at the edges of the images in the collage | type=bool | choices=[True, False]
+  useRoundedCorners: true
+  # Factor how much the objects (humans, animals, ...) in the image are considered for weighting the image size | type=float
+  imageScoreFactor: 2.0
   # Use short weekday names (e.g., Mon, Tue) | type=bool | choices=[True, False]
   useShortDayNames: false
   # Use short month names (e.g., Jan, Feb) | type=bool | choices=[True, False]

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/docs/usage/config.md

@@ -5,9 +5,14 @@ The parameters in the cli category can be accessed via the command line interfac
 
 ## Category "app"
 
-| Name      | Type | Description                       | Default | Choices                                           |
-|-----------|------|-----------------------------------|---------|---------------------------------------------------|
-| log_level | str  | Logging level for the application | 'INFO'  | ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] |
+| Name                   | Type | Description                                 | Default    | Choices                                                                                                                                               |
+|------------------------|------|---------------------------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
+| date_format            | str  | Date format to use                          | '%Y-%m-%d' | -                                                                                                                                                     |
+| log_level              | str  | Logging level for the application           | 'INFO'     | ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']                                                                                                     |
+| log_file_max_size      | int  | Maximum log file size in MB before rotation | 2          | -                                                                                                                                                     |
+| enable_file_logging    | bool | Enable logging to file                      | True       | [True, False]                                                                                                                                         |
+| enable_console_logging | bool | Enable logging to console                   | True       | [True, False]                                                                                                                                         |
+| theme                  | str  | GUI theme setting supported by ttkbootstrap | 'darkly'   | ['cosmo', 'flatly', 'litera', 'minty', 'lumen', 'sandstone', 'yeti', 'pulse', 'united', 'darkly', 'superhero', 'solar', 'cyborg', 'vapor', 'simplex'] |
 
 ## Category "general"
 
@@ -59,15 +64,17 @@ The parameters in the cli category can be accessed via the command line interfac
 
 ## Category "layout"
 
-| Name                | Type | Description                                                                                         | Default | Choices       |
-|---------------------|------|-----------------------------------------------------------------------------------------------------|---------|---------------|
-| marginTop           | int  | Top margin in mm                                                                                    | 6       | -             |
-| marginBottom        | int  | Bottom margin in mm                                                                                 | 3       | -             |
-| marginSides         | int  | Side margins in mm                                                                                  | 3       | -             |
-| spacing             | int  | Spacing between elements in mm                                                                      | 2       | -             |
-| useShortDayNames    | bool | Use short weekday names (e.g., Mon, Tue)                                                            | False   | [True, False] |
-| useShortMonthNames  | bool | Use short month names (e.g., Jan, Feb)                                                              | True    | [True, False] |
-| usePhotoDescription | bool | Include photo descriptions in the collage                                                           | True    | [True, False] |
-| generatePdf         | bool | Combine all generated collages into one pdf                                                         | True    | [True, False] |
-| objectRecognition   | bool | Use neuronal network YOLO (You Only Look Once) object detection model to crop images content-aware. | True    | [True, False] |
+| Name                | Type  | Description                                                                                                 | Default | Choices       |
+|---------------------|-------|-------------------------------------------------------------------------------------------------------------|---------|---------------|
+| marginTop           | int   | Top margin in mm                                                                                            | 6       | -             |
+| marginBottom        | int   | Bottom margin in mm                                                                                         | 3       | -             |
+| marginSides         | int   | Side margins in mm                                                                                          | 3       | -             |
+| spacing             | int   | Spacing between elements in mm                                                                              | 2       | -             |
+| useRoundedCorners   | bool  | Use rounded corners at the edges of the images in the collage                                               | True    | [True, False] |
+| imageScoreFactor    | float | Factor how much the objects (humans, animals, ...) in the image are considered for weighting the image size | 2.0     | -             |
+| useShortDayNames    | bool  | Use short weekday names (e.g., Mon, Tue)                                                                    | False   | [True, False] |
+| useShortMonthNames  | bool  | Use short month names (e.g., Jan, Feb)                                                                      | True    | [True, False] |
+| usePhotoDescription | bool  | Include photo descriptions in the collage                                                                   | True    | [True, False] |
+| generatePdf         | bool  | Combine all generated collages into one pdf                                                                 | True    | [True, False] |
+| objectRecognition   | bool  | Use neuronal network YOLO (You Only Look Once) object detection model to crop images content-aware.         | True    | [True, False] |
 

photo_composition_designer-1.0.2/images/descriptions.txt

@@ -0,0 +1,9 @@
+title: Description text for week title
+week_1: Description text for week week_1
+week_2: Description text for week week_2
+week_3: Description text for week week_3
+week_4: Description text for week week_4
+week_5: Description text for week week_5
+week_6_testimages_3: Description text for week week_6_testimages_3
+week_7_testimages_4: Description text for week week_7_testimages_4
+week_8_testimages_5: Description text for week week_8_testimages_5

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/pyproject.toml

@@ -9,7 +9,8 @@ readme = "docs/index.md"
 requires-python = ">=3.11,<4.0"
 dependencies = [
     "astral>=3.2",
-    "config-cli-gui>=0.3.2",
+    "config-cli-gui>=0.3.5",
+    "ttkbootstrap>=1.20.3",
     "exifread>=3.5.1",
     "geopandas>=1.1.1",
     "holidays>=0.84",

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/src/Photo_Composition_Designer/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.1'
-__version_tuple__ = version_tuple = (1, 0, 1)
+__version__ = version = '1.0.2'
+__version_tuple__ = version_tuple = (1, 0, 2)
 
-__commit_id__ = commit_id = 'gd3847087e'
+__commit_id__ = commit_id = 'gfd5b3ded1'

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/src/Photo_Composition_Designer/common/Photo.py

@@ -69,7 +69,7 @@ class Photo:
         """Returns an Image object if the file can be opened."""
         try:
             return Image.open(self.file_path)
-        except Exception as e:
+        except (OSError, SyntaxError) as e:
             print(f"Error opening image: {e}")
             return None
 
@@ -113,7 +113,7 @@ class Photo:
 
 def get_photos_from_dir(
     image_folder: Path, locations: dict[str, tuple[float, float]] = None
-) -> list["Photo"] | None:
+) -> list[Photo]:
     """
     Reads all image files from a folder and returns a list of Photo objects.
     """
@@ -129,11 +129,7 @@ def get_photos_from_dir(
         if file.lower().endswith((".png", ".jpg", ".jpeg"))
     ]
 
-    if not image_files:
-        print(f"No images found in '{image_folder}'.")
-        return None
-
-    return [Photo(Path(file), locations) for file in image_files]  # Create Photo objects
+    return [Photo(Path(file), locations) for file in image_files]
 
 
 def get_photo_dates(photos: list[Photo]) -> str:

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/src/Photo_Composition_Designer/config/config.py

@@ -15,20 +15,6 @@ from config_cli_gui.configtypes.font import Font
 from config_cli_gui.docs import DocumentationGenerator
 
 
-class AppConfig(ConfigCategory):
-    """Application-specific configuration parameters."""
-
-    def get_category_name(self) -> str:
-        return "app"
-
-    log_level: ConfigParameter = ConfigParameter(
-        name="log_level",
-        value="INFO",
-        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
-        help="Logging level for the application",
-    )
-
-
 class GeneralConfig(ConfigCategory):
     """GENERAL configuration parameters."""
 
@@ -239,6 +225,19 @@ class LayoutConfig(ConfigCategory):
         help="Spacing between elements in mm",
     )
 
+    useRoundedCorners: ConfigParameter = ConfigParameter(
+        name="useRoundedCorners",
+        value=True,
+        help="Use rounded corners at the edges of the images in the collage",
+    )
+
+    imageScoreFactor: ConfigParameter = ConfigParameter(
+        name="imageScoreFactor",
+        value=2.0,
+        help="Factor how much the objects (humans, animals, ...) in the image "
+        "are considered for weighting the image size",
+    )
+
     useShortDayNames: ConfigParameter = ConfigParameter(
         name="useShortDayNames",
         value=False,
@@ -274,7 +273,6 @@ class LayoutConfig(ConfigCategory):
 class ConfigParameterManager(ConfigManager):
     """Main configuration manager that handles all parameter categories."""
 
-    app: AppConfig
     general: GeneralConfig
     calendar: CalendarConfig
     style: StyleConfig
@@ -284,7 +282,6 @@ class ConfigParameterManager(ConfigManager):
 
     def __init__(self, config_file: str | None = None, **kwargs):
         categories = (
-            AppConfig(),
             GeneralConfig(),
             CalendarConfig(),
             StyleConfig(),

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/src/Photo_Composition_Designer/core/base.py

@@ -11,12 +11,17 @@ from config_cli_gui.logging import get_logger, initialize_logging
 from PIL import Image, ImageDraw
 
 from Photo_Composition_Designer.common.Locations import Locations
-from Photo_Composition_Designer.common.Photo import Photo, get_photo_dates, get_photos_from_dir
+from Photo_Composition_Designer.common.Photo import (
+    Photo,
+    get_photo_dates,
+    get_photos_from_dir,
+)
 from Photo_Composition_Designer.config.config import ConfigParameterManager
 from Photo_Composition_Designer.image.CalendarRenderer import CalendarRenderer
 from Photo_Composition_Designer.image.CollageRenderer import CollageRenderer
 from Photo_Composition_Designer.image.DescriptionRenderer import DescriptionRenderer
 from Photo_Composition_Designer.image.MapRenderer import MapRenderer
+from Photo_Composition_Designer.image.ObjectDetector import ObjectDetector  # Import ObjectDetector
 from Photo_Composition_Designer.tools.Helpers import mm_to_px
 
 
@@ -73,6 +78,11 @@ class CompositionDesigner:
         # colors
         background_color = self.config.style.backgroundColor.value.to_pil()
 
+        # Create ObjectDetector instance once
+        self.object_detector = ObjectDetector() if self.use_object_recognition else None
+        if self.object_detector:
+            self.object_detector.clear_cache()
+
         # Create other helpers/generators — pass config object for them to pull values from.
         self.mapGenerator: MapRenderer = MapRenderer.from_config(self.config)
         self.descGenerator: DescriptionRenderer = DescriptionRenderer.from_config(self.config)
@@ -87,6 +97,9 @@ class CompositionDesigner:
             self.spacing_px,
             background_color,
             self.use_object_recognition,
+            self.config.layout.useRoundedCorners.value,
+            self.config.layout.imageScoreFactor.value,
+            self.object_detector,  # Pass the shared ObjectDetector instance
         )
         start_date_cfg = self.config.calendar.startDate.value
         if self.compositionTitle:
@@ -145,7 +158,8 @@ class CompositionDesigner:
                 self.compositionTitle, available_cal_width, self.calendar_height_px
             )
             composition.paste(
-                title_img, (self.margin_sides_px, self.height_px - self.calendar_height_px)
+                title_img,
+                (self.margin_sides_px, self.height_px - self.calendar_height_px),
             )
         elif self.config.calendar.useCalendar.value:
             if self.config.geo.usePhotoLocationMaps.value:
@@ -229,7 +243,10 @@ class CompositionDesigner:
                 photo_description = [text_file.stem]
         return photo_description
 
-    def generate_compositions_from_folder(self, folder_name: str) -> Image.Image | None:
+    def generate_compositions_from_folder(
+        self,
+        folder_name: str,
+    ) -> Image.Image | None:
         """
         Generates a single collage for the given folder name.
         Returns True if a composition was generated, False if skipped.
@@ -301,7 +318,7 @@ class CompositionDesigner:
         output_file_name = f"{output_prefix}.jpg"
         output_path = self.outputDir / output_file_name
         jpg_quality = int(self.config.size.jpgQuality.value)
-        dpi_tuple = (self.dpi, self.dpi)
+        dpi_tuple = (self.dpi, self.dpi)  # Use original DPI for saving
         composition.save(output_path, quality=jpg_quality, dpi=dpi_tuple)
         self.logger.info(f"Composition saved: {output_path}")
 

{photo_composition_designer-1.0.1 → photo_composition_designer-1.0.2}/src/Photo_Composition_Designer/gui/GuiLogWriter.py

@@ -45,13 +45,19 @@ class GuiLogWriter:
                         tag_name = f"link_{len(self.hyperlink_tags)}"
                         self.text_widget.tag_config(tag_name, foreground="blue", underline=True)
                         self.text_widget.tag_bind(
-                            tag_name, "<Button-1>", lambda e, p=path: self._open_path_in_explorer(p)
+                            tag_name,
+                            "<Button-1>",
+                            lambda e, p=path: self._open_path_in_explorer(p),
                         )
                         self.text_widget.tag_bind(
-                            tag_name, "<Enter>", lambda e: self.text_widget.config(cursor="hand2")
+                            tag_name,
+                            "<Enter>",
+                            lambda e: self.text_widget.config(cursor="hand2"),
                         )
                         self.text_widget.tag_bind(
-                            tag_name, "<Leave>", lambda e: self.text_widget.config(cursor="")
+                            tag_name,
+                            "<Leave>",
+                            lambda e: self.text_widget.config(cursor=""),
                         )
                         self.text_widget.tag_add(tag_name, start_index, end_index)
                         self.hyperlink_tags[tag_name] = path