Photo-Composition-Designer 1.0.0__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.0 → photo_composition_designer-1.0.2}/HISTORY.md

@@ -4,6 +4,83 @@ 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]
+- Object recognition: add tests, add improved cropping and object
+  prioritization, add test images. [Paul Magister]
+- Object recognition: add tests, add improved cropping and object
+  prioritization, add test images. [Paul Magister]
+- Object recognition: improve module structure, add SmartCrop test.
+  [Paul Magister]
+- Object recognition: improve module structure. [Paul Magister]
+- Image recognition: add parameter whether to use object recognition.
+  [Paul Magister]
+- Image recognition: add example images for improved testing. [Paul
+  Magister]
+- Image recognition: use onnx file and onnxruntime instead of
+  ultralytics and pytorch. [Paul Magister]
+- Image recognition: detect not only persons, but different objects.
+  [Paul Magister]
+- Collage designer: using YOLO for object recognition. [Paul Magister]
+- Make pytree: consider doc strings. [Paul Magister]
+- Make pytree: improvements on show_tree.py: rename to
+  project_structure.py. [Paul Magister]
+- Make pytree: improvements on show_tree.py: doc external tool. [Paul
+  Magister]
+- Make pytree: improvements on show_tree.py: bild compact llm
+  understandable json, consider functions. [Paul Magister]
+- Make pytree: improvements on show_tree.py: - class attributes,
+  instance attributes. [Paul Magister]
+- Pipx in doc, support python until <4.0. [Paul Magister]
+
+
+1.0.0 (2025-12-04)
+------------------
+- Docs: Update HISTORY.md for release 1.0.0. [Paul Magister]
 - Upgrade libs. [Paul Magister]
 - Fix doc: start app from pypi. [Paul Magister]
 

{photo_composition_designer-1.0.0 → 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.0 → photo_composition_designer-1.0.2}/Makefile

@@ -257,11 +257,11 @@ list:            ## Show project file list (excluding ignored folders)
 
 .PHONY: tree
 tree:            ## Show project tree (excluding ignored folders)
-	@uv run ./scripts/show_tree.py
+	@uv run ./scripts/project_structure.py
 
 .PHONY: pytree
 pytree:            ## Show project tree (excluding ignored folders)
-	@uv run ./scripts/show_tree.py --show-code
+	@uv run ./scripts/project_structure.py --json --md --llm --doc-string
 
 .PHONY: init
 init:             ## Initialize the project based on an application template.

{photo_composition_designer-1.0.0/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.0
+Version: 1.0.2
 Summary: Feature-rich Python project template for Photo-Composition-Designer.
 Author: pamagister
-Requires-Python: <3.12,>=3.10
+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
@@ -15,6 +16,8 @@ Requires-Dist: matplotlib>=3.10.7
 Requires-Dist: pillow>=12.0.0
 Requires-Dist: pytz>=2025.2
 Requires-Dist: shapely>=2.1.1
+Requires-Dist: onnxruntime>=1.26.0
+Requires-Dist: numpy>=2.4.6
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == "dev"
 Requires-Dist: pytest-mock>=3.14.1; extra == "dev"
@@ -81,6 +84,10 @@ Download from [PyPI](https://pypi.org/).
 ```bash
 pip install Photo-Composition-Designer
 ```
+or
+```bash
+pipx install Photo-Composition-Designer
+```
 
 Run GUI from command line
 

{photo_composition_designer-1.0.0 → photo_composition_designer-1.0.2}/README.md

@@ -47,6 +47,10 @@ Download from [PyPI](https://pypi.org/).
 ```bash
 pip install Photo-Composition-Designer
 ```
+or
+```bash
+pipx install Photo-Composition-Designer
+```
 
 Run GUI from command line
 

{photo_composition_designer-1.0.0 → 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]
@@ -68,4 +82,6 @@ layout:
   # Include photo descriptions in the collage | type=bool | choices=[True, False]
   usePhotoDescription: true
   # Combine all generated collages into one pdf | type=bool | choices=[True, False]
-  generatePdf: true
+  generatePdf: true
+  # Use neuronal network YOLO (You Only Look Once) object detection model to crop images content-aware. | type=bool | choices=[True, False]
+  objectRecognition: true

{photo_composition_designer-1.0.0 → photo_composition_designer-1.0.2}/docs/index.md

@@ -45,6 +45,10 @@ Download from [PyPI](https://pypi.org/).
 ```bash
 pip install Photo-Composition-Designer
 ```
+or
+```bash
+pipx install Photo-Composition-Designer
+```
 
 Run GUI from command line
 

{photo_composition_designer-1.0.0 → 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,14 +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] |
+| 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.0 → photo_composition_designer-1.0.2}/pyproject.toml

@@ -6,10 +6,11 @@ authors = [
     {name = "pamagister"}
 ]
 readme = "docs/index.md"
-requires-python = ">=3.10,<3.12"
+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",
@@ -17,6 +18,8 @@ dependencies = [
     "pillow>=12.0.0",
     "pytz>=2025.2",
     "shapely>=2.1.1",
+    "onnxruntime>=1.26.0",
+    "numpy>=2.4.6"
 ]
 
 # Dev dependencies as optional dependencies

{photo_composition_designer-1.0.0 → photo_composition_designer-1.0.2}/scripts/generate_config_docs.py

@@ -1,4 +1,4 @@
-from config_cli_gui.docs_generator import DocumentationGenerator
+from config_cli_gui.docs import DocumentationGenerator
 
 from Photo_Composition_Designer.config.config import ConfigParameterManager