Beta version

Gnomonic Projection Package v0.1.0-beta

Release Date: (Insert Date)

Overview

This beta release of the Gnomonic Projection Package offers a modular, component-based architecture for forward and inverse gnomonic (and mercator) projections. By leveraging standardized base classes and a registry-driven approach, users can easily integrate new projection types into their workflows.

Key Objects

1. ProjectionRegistry

   • Central hub to register, list, and retrieve projection configurations.
   • Standardizes the interface for projections by enforcing a common set of components: config class, grid generation class, strategy class, etc.
   • Encourages a plug-in style approach, making it simple to add or swap out projections.

2. ProjectionProcessor

   • Orchestrates the projection workflow from start to finish.
   • Handles forward and backward projection logic by combining the strategy, grid generation, interpolation, and coordinate transformation components defined in the registry.
   • Simplifies usage so developers only need to call forward(...) or backward(...) on their images with minimal extra setup.

Standardized Approach

• Reusable Base Classes
  The package defines a series of base abstract classes:

  • BaseProjectionConfig: Pydantic-backed configuration validation.
  • BaseGridGeneration: Grid creation logic.
  • BaseProjectionStrategy: Forward/backward projection methods.
  • BaseInterpolation: Image interpolation (e.g., via OpenCV).
  • BaseCoordinateTransformer: Geospatial transformations between spherical and image coordinates.

  By extending these base classes, new projections can be implemented quickly using a familiar, consistent set of files and methods. This standardization reduces boilerplate and keeps the codebase structured.

• Registry-Driven Design
  Thanks to the ProjectionRegistry, all new projection classes can be registered under a unique name. Once registered, any user can simply call:

  processor = ProjectionRegistry.get_projection("my_custom_projection", return_processor=True)

  This yields a ProjectionProcessor instance that already knows how to perform the forward/backward transformations of the new projection.

Example Usage

from projection.registry import ProjectionRegistry

# Retrieve a ready-to-use Gnomonic processor from the registry
gnomonic_processor = ProjectionRegistry.get_projection(
    name="gnomonic", 
    return_processor=True,
    R=6371,      # Earth’s approximate radius in km
    fov_deg=120  # Field of view
)

# Forward project an equirectangular panorama
import cv2
input_img = cv2.imread("equirectangular_input.jpg")
projected_img = gnomonic_processor.forward(input_img)
cv2.imwrite("gnomonic_output.jpg", projected_img)

Adding New Projections

To add a new projection:

1. Create a config class (extending BaseProjectionConfig) and define your parameters (like radius, resolution, etc.).
2. Implement a grid generation class (extending BaseGridGeneration) for forward/backward coordinate grids.
3. Subclass BaseProjectionStrategy to handle custom forward and inverse projection formulas.
4. (Optional) Implement a specialized BaseCoordinateTransformer if you need custom spherical/image transformations.
5. Register everything in the ProjectionRegistry with:

   from projection.registry import ProjectionRegistry
   
   ProjectionRegistry.register("my_projection", {
       "config": MyProjectionConfig,
       "grid_generation": MyGridGeneration,
       "projection_strategy": MyProjectionStrategy,
       "transformer": MyCoordinateTransformer,  # optional, if needed
   })

   Once registered, you can retrieve a ProjectionProcessor or configuration as needed.

Feedback & Next Steps

This beta release aims to unify projection logic under one flexible, extensible framework:

• Testing: We encourage you to try out Gnomonic or Mercator projections with real-world data and report any issues.
• Contributions: We welcome pull requests introducing new projection types or improvements to our base classes.
• Future Plans: Adding more robust transformations, higher-level wrappers, and improved documentation for advanced scenarios.

Thank you for exploring the Gnomonic Projection Package v0.1.0-beta!