Metadata-Version: 2.4
Name: py-canonicalizer
Version: 0.1.0
Summary: A universal tool for preparing polyline data for algorithms like RDP, by solving the arbitrary start-point problem.
Author-email: Your Name <your_email@example.com>
Keywords: rdp-algorithm,polyline-simplification,canonical,computational-geometry,gis,rhino,grasshopper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy

# py-canonicalizer: A Universal Tool for Polyline Canonicalization
	- This Python package is designed to solve a common problem in computational geometry and CAD workflows: the arbitrary start-point and direction of polylines. It provides a robust, universal algorithm to standardize 3D point lists, making them predictable and ready for further processing by algorithms like the Ramer-Douglas-Peucker (RDP) algorithm.
	- This ensures that your algorithmic results are consistent every time, regardless of the original data's orientation.
- ## Features
	- **Application-Agnostic:** Works with any Python environment, with no dependencies on specific CAD or GIS software.
	- **Rule-Based Standardization:** Uses a clear, hierarchical set of rules (based on centroid proximity and coordinate values) to define a canonical starting point and direction.
	- **Data Cleaning:** Automatically handles duplicate points in closed polylines to prevent calculation errors.
- ## Installation
	- You can install the package directly from PyPI using pip:
	- ```bash
	  pip install py-canonicalizer
	  ```
- ## Usage
	- The core function `canonicalize_points` takes a NumPy array and returns a new, ordered array.
	- ```
	  import numpy as np
	  from py_canonicalizer import canonicalize_points
	  
	  # Example: a simple closed polyline with an arbitrary start point
	  original_points = np.array([[1, 1, 0], [2, 3, 0], [5, 4, 0], [4, 1, 0], [1, 1, 0]])
	  
	  # Get the canonicalized version
	  canonical_points = canonicalize_points(original_points)
	  
	  print(canonical_points)
	  # Output will always be consistently ordered regardless of the input's original orientation.
	  ```
-
- ## How It Works
	- The algorithm is based on a set of rules and a hierarchical tie-breaker system to ensure a single, repeatable result for any given point cloud.
	- **Data Cleaning:** The algorithm first removes duplicate points, which often appear at the end of closed polylines.
	- **Canonical Start Point:** It finds the point closest to the geometric center (centroid) of the polyline.
	- **Hierarchical Tie-breaker:** If multiple points are equally close, it uses a predictable rule (max X, then max Y, then max Z) to select the starting point.
	- **Direction:** It then compares the neighbors of the start point using the same tie-breaker rule to determine the polyline's final, standardized direction (e.g., clockwise vs. counter-clockwise).
- ## License
	- This project is licensed under the MIT License.
