hazy-frames 0.1.0__tar.gz → 0.2.0__tar.gz

hazy_frames-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: CI
+on:
+  push:
+    branches: ["main", "feat/**"]
+  pull_request:
+    branches: ["main"]
+permissions:
+  contents: read
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run ruff format check
+        run: uv run ruff format --check .
+
+      - name: Run ruff lint
+        run: uv run ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest --cov=src/hazy --cov-report=term --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          file: ./coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}

hazy_frames-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          draft: false
+          prerelease: false
+          body_path: CHANGELOG.md

hazy_frames-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,35 @@
+# Pre-commit hooks configuration
+# See https://pre-commit.com for more information
+
+repos:
+  # Ruff - fast Python linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      # Run the linter
+      - id: ruff
+        args: [--fix]
+        language: system
+      # Run the formatter
+      - id: ruff-format
+        language: system
+
+  # Strip output from Jupyter notebooks
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout
+        language: system
+
+  # General file cleaning hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # Remove trailing whitespace
+      - id: trailing-whitespace
+      # Ensure files end with a newline
+      - id: end-of-file-fixer
+      # Check for files that would conflict on case-insensitive filesystems
+      - id: check-case-conflict
+      # Check for merge conflicts
+      - id: check-merge-conflict

hazy_frames-0.2.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+sphinx:
+  configuration: docs/conf.py

hazy_frames-0.2.0/CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Transformation Clear Methods**: New methods to reset transformations
+  - `Frame.clear_rotations()` - Reset all rotations to identity
+  - `Frame.clear_translations()` - Reset all translations to zero
+  - `Frame.clear_scalings()` - Reset all scalings to identity
+  - `Frame.clear_all_transforms()` - Reset all transformations at once
+
+- **Array Input Support**: Enhanced NumPy integration for transformation methods
+  - `Frame.translate()` now accepts array input: `translate([x, y, z])`
+  - `Frame.scale()` now accepts array input: `scale([x, y, z])`
+  - Maintains backward compatibility with existing APIs
+
+- **Examples**: New advanced optical raytracing example
+  - `03-simple-robot-arm.ipynb`: Robot arm kinematics with hierarchical frames and animation
+  - `04-simple-raytracing.ipynb`: Optical raytracing through lens surfaces
+    - Demonstrates frame transformations simplifying optical system design
+    - Implements meridional plane reduction for axisymmetric surfaces
+    - Shows spherical and hyperbolic lens profiles with aberration visualization
+    - Features immutable Ray class with Snell's law vector refraction
+
+### Changed
+
+- **Improved Error Messages**: Better validation and error messages for transformation methods
+  - `Frame.scale()` provides clearer guidance when mixing scalar and per-axis arguments
+  - Validates array shapes and provides helpful error messages
+
+## [0.2.0] - 2025-11-15
+
+### Added
+
+- **Comprehensive NumPy Integration**: Native support for NumPy arrays and batch operations
+  - `from_array()` factory methods for `Point` and `Vector` classes
+  - `list_from_array()` for batch creation from NumPy arrays
+  - Support for array-like inputs in `Frame.point()` and `Frame.vector()`
+  - NumPy stack operations (`np.stack()`, `np.hstack()`, `np.vstack()`) for primitives
+  - Compatibility with NumPy scalar types (`np.float64`, `np.int32`, etc.)
+  - Dedicated test suite for NumPy integration (`tests/test_numpy_integration.py`)
+
+- **Custom Formatters**: `__format__()` method for `GeometricPrimitive` with multiple output styles
+  - Standard format specifiers (e.g., `:6.2f`, `:.3f`, `:10.4e`) format all three components
+  - `'a'`: Array-only format without class name or frame info
+  - `'n'`: No-frame format showing only class name and coordinates
+  - Default: Full format with class name and frame
+
+- **Multi-Index Support**: `__getitem__()` now supports advanced NumPy indexing
+  - Integer indexing: `primitive[0]` returns float
+  - Slicing: `primitive[0:2]` returns NDArray
+  - Fancy indexing: `primitive[[0, 2]]` returns NDArray
+
+- **Quaternion Rotation Support**: `Frame.rotate_quat()` method for quaternion-based rotations
+
+- **Child Frame Creation**: `Frame.make_child()` method to create child frames directly
+
+- **Batch Transformations**: Explicit methods for batch operations
+  - `batch_transform_points()` for transforming multiple points
+  - `batch_transform_vectors()` for transforming multiple vectors
+
+- **Parent-Child Tracking**: Frames now maintain bidirectional parent-child relationships
+  - Each frame tracks its direct children
+  - Cache invalidation propagates recursively through the hierarchy
+
+- **Documentation**: Complete Sphinx documentation with ReadTheDocs integration
+  - Installation guide, quick start tutorial, and API reference
+  - Jupyter notebook examples integrated via nbsphinx
+  - Available at [hazy-frames.readthedocs.io](https://hazy-frames.readthedocs.io/)
+
+- **Examples**: Two interactive Jupyter notebooks demonstrating core concepts
+  - `01-surface_intersections.ipynb`: Ray-plane intersection with coordinate transformations
+  - `02-frame-hierarchies.ipynb`: Parent-child relationships and dynamic transformations
+
+- **CI/CD**: GitHub Actions workflow with pytest, ruff linting, and codecov integration
+
+- **Pre-commit Hooks**: Automated code quality checks with ruff linter and formatter
+
+### Changed
+
+- **API Naming Improvements**: More consistent and pythonic naming conventions
+  - Removed `coords` property (use `np.array(primitive)` instead)
+  - Renamed `unit_x/y/z` to `axis_x/y/z` for frame axes
+  - Removed `make_` prefix from `Frame.point()` and `Frame.vector()` methods
+  - Simplified `Frame.scale()` API: uniform scaling with single argument, per-axis with three
+
+- **Root Frame Handling**: Removed implicit singleton pattern
+  - Frames can now be orphans (no parent) instead of defaulting to global singleton
+  - More explicit frame hierarchy management
+
+- **API Documentation**: Comprehensive docstrings with examples for all public methods
+
+### Fixed
+
+- **Cache Invalidation**: Parent frame modifications now properly invalidate child frame caches
+  - Previously, modifying a parent would cause stale transformations in child frames
+  - Cache invalidation now propagates recursively through the entire hierarchy
+
+- **Vector Batch Transform**: Fixed critical bug in `batch_transform_vectors_global()` using incorrect homogeneous coordinate (was `w=1`, now correctly `w=0`)
+
+- **Parent Immutability**: Frame parent is now immutable after creation to maintain hierarchy consistency
+
+### Removed
+
+- **Legacy Methods**: Removed redundant `Vector.unit_x/y/z()` methods (use `frame.axis_x/y/z` instead)
+
+## [0.1.0] - 2025-11-09
+
+Initial release of hazy-frames.
+
+### Added
+
+- Hierarchical frame system with parent-child relationships
+- Frame-aware geometric primitives (`Point` and `Vector`)
+- Automatic coordinate transformations between frames
+- Transformation caching for performance
+- Type-safe geometric arithmetic (e.g., Point - Point = Vector)
+- Support for rotation (Euler angles), translation, and scaling
+- NumPy array conversion via `__array__()` protocol
+- Comprehensive test suite with pytest
+- MIT License
+
+[Unreleased]: https://github.com/Littie28/hazy-frames/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/Littie28/hazy-frames/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Littie28/hazy-frames/releases/tag/v0.1.0