# 2D Conehull
This package uses the quickhull algorithm to find the convex hull of a point set,
but with the added option of restricting the set of halfplanes we intersect over to only those with normals lying in a given convex cone.
## Features
- **Cone-Constrained Hull**: The cone feature computes the intersection of halfplanes whose outward normals lie between two specified direction vectors. This creates a larger (unbounded) region that contains the original convex hull.
- **Visualizations**: View a step-by-step visualization of the algorithm.
- **Samplers**: For convenience we include simple ways of creating point sets, by inputting either an implicit (in)equality or a parametrization.
## Basic Usage
```python
import numpy as np
# Make conehull accessible
import sys
import os
sys.path.append(os.path.dirname(os.getcwd()))
from conehull import conehull
from conehull.view import plot_hull
points = np.array([
[ 3.0, -4.0],
[-1.0, 0.0],
[ 3.0, 5.0],
[ 4.5, 1.0],
[-6.0, -2.0],
[ 0.0, 4.0],
[ 5.0, 2.0],
[-2.0, -5.0],
[ 1.0, 2.0],
[ 2.0, 6.0],
[-5.5, 1.5],
[ 6.0, -1.0],
[-3.0, 7.0],
[ 3.0, 0.0],
[ 2.0, -2.5],
[ 4.0, 0.0],
[-7.0, 3.0],
[-4.0, -0.5],
])
cone = np.array([[1, 0], [0, 1]])
cone_hull = conehull(points, cone=cone)
# plot_hull is just a convenience wrapper around pyplot
plot_hull(cone_hull, points, cone=cone, show_convex_hull=True,
title="Cone hull with standard convex hull comparison")
```
## Visualization Modes
```python
# Import visualization functions
from conehull.view import (
conehull_animated,
conehull_step_by_step,
conehull_jupyter,
plot_hull
)
# 1. Animated visualization - auto-playing GIF/video
# Creates a smooth animation showing algorithm steps
conehull_animated(points, cone=cone, save_path="animation.gif", interval=800)
# 2. Step-by-step interactive viewer - returns navigation functions
# Best for understanding algorithm mechanics step by step
hull, frames, show_frame = conehull_step_by_step(points, cone=cone)
# Use the returned show_frame function to navigate:
show_frame(0) # Show first step
show_frame(5) # Jump to step 5
show_frame(-1) # Show final result
# 3. Jupyter widget - interactive controls in notebooks
# Returns a widget object with navigation buttons and sliders
if 'ipywidgets' in globals(): # Only works in Jupyter
viewer = conehull_jupyter(points, cone=cone)
viewer.show() # Display the interactive widget
# 4. Static hull plot - simple visualization with comparison option
plot_hull(hull=cone_hull, points=points, cone=cone,
show_convex_hull=True, save_path="comparison.png")
```
## Configurable Bounding Box
Since the hull is unbounded for any nontrivial cone, we use a bounding box.
The `cone_bounds` parameter controls how the unbounded cone hull is clipped:
```python
# Default: margin = 2.0 times data range
cone_hull = conehull(points, cone=cone)
# Custom margin multiplier
cone_hull = conehull(points, cone=cone, cone_bounds=5.0)
# Explicit bounds: [x_min, x_max, y_min, y_max]
cone_hull = conehull(points, cone=cone, cone_bounds=[-10, 10, -10, 10])
# Alternative format: [[x_min, y_min], [x_max, y_max]]
cone_hull = conehull(points, cone=cone, cone_bounds=[[-10, -10], [10, 10]])
```
## Files
- `_geometry.py` - Basic geometric operations like point-to-line distances and determining which side of a line points are on. Also handles sorting hull points in counterclockwise order.
- `_conehull.py` - Implements the QuickHull algorithm for both standard and cone-constrained convex hulls. Contains the main `conehull()` function and recursive hull construction logic.
- `_cone_intersection.py` - Transforms standard convex hulls into cone hulls by filtering halfplanes based on cone constraints. Computes intersections within configurable bounding boxes.
- `view.py` - Visualization tools including step-by-step animations, interactive Jupyter widgets, and static plotting. Supports both automated playback and manual navigation of algorithm steps.
- `sampler.py` - Generates test point datasets from mathematical functions. Supports parametric curves, implicit equations, and region sampling for creating diverse test cases.
Raw data
{
"_id": null,
"home_page": null,
"name": "conehull",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "convex hull, computational geometry, quickhull, cone constraints, visualization",
"author": null,
"author_email": "Tryggvi Kalman J\u00f3nsson <tryggvikalman@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/84/fa/a6a05c71c4847dba25b8d68c191c6c472d709e78f9955986debda0aa6693/conehull-1.0.0.post3.tar.gz",
"platform": null,
"description": "# 2D Conehull\n\nThis package uses the quickhull algorithm to find the convex hull of a point set,\nbut with the added option of restricting the set of halfplanes we intersect over to only those with normals lying in a given convex cone.\n\n## Features\n\n- **Cone-Constrained Hull**: The cone feature computes the intersection of halfplanes whose outward normals lie between two specified direction vectors. This creates a larger (unbounded) region that contains the original convex hull.\n- **Visualizations**: View a step-by-step visualization of the algorithm.\n- **Samplers**: For convenience we include simple ways of creating point sets, by inputting either an implicit (in)equality or a parametrization.\n\n## Basic Usage\n\n```python\nimport numpy as np\n\n# Make conehull accessible\nimport sys\nimport os\nsys.path.append(os.path.dirname(os.getcwd()))\n\nfrom conehull import conehull\nfrom conehull.view import plot_hull\n\npoints = np.array([\n [ 3.0, -4.0],\n [-1.0, 0.0],\n [ 3.0, 5.0],\n [ 4.5, 1.0],\n [-6.0, -2.0],\n [ 0.0, 4.0],\n [ 5.0, 2.0],\n [-2.0, -5.0],\n [ 1.0, 2.0],\n [ 2.0, 6.0],\n [-5.5, 1.5],\n [ 6.0, -1.0],\n [-3.0, 7.0],\n [ 3.0, 0.0],\n [ 2.0, -2.5],\n [ 4.0, 0.0],\n [-7.0, 3.0],\n [-4.0, -0.5],\n])\ncone = np.array([[1, 0], [0, 1]])\n\ncone_hull = conehull(points, cone=cone)\n\n# plot_hull is just a convenience wrapper around pyplot\nplot_hull(cone_hull, points, cone=cone, show_convex_hull=True, \n title=\"Cone hull with standard convex hull comparison\")\n```\n\n\n\n## Visualization Modes\n\n```python\n# Import visualization functions\nfrom conehull.view import (\n conehull_animated,\n conehull_step_by_step, \n conehull_jupyter,\n plot_hull\n)\n\n# 1. Animated visualization - auto-playing GIF/video\n# Creates a smooth animation showing algorithm steps\nconehull_animated(points, cone=cone, save_path=\"animation.gif\", interval=800)\n\n# 2. Step-by-step interactive viewer - returns navigation functions\n# Best for understanding algorithm mechanics step by step\nhull, frames, show_frame = conehull_step_by_step(points, cone=cone)\n\n# Use the returned show_frame function to navigate:\nshow_frame(0) # Show first step\nshow_frame(5) # Jump to step 5\nshow_frame(-1) # Show final result\n\n# 3. Jupyter widget - interactive controls in notebooks\n# Returns a widget object with navigation buttons and sliders\nif 'ipywidgets' in globals(): # Only works in Jupyter\n viewer = conehull_jupyter(points, cone=cone)\n viewer.show() # Display the interactive widget\n\n# 4. Static hull plot - simple visualization with comparison option\nplot_hull(hull=cone_hull, points=points, cone=cone, \n show_convex_hull=True, save_path=\"comparison.png\")\n```\n\n\n## Configurable Bounding Box\n\nSince the hull is unbounded for any nontrivial cone, we use a bounding box.\nThe `cone_bounds` parameter controls how the unbounded cone hull is clipped:\n\n```python\n# Default: margin = 2.0 times data range\ncone_hull = conehull(points, cone=cone)\n\n# Custom margin multiplier\ncone_hull = conehull(points, cone=cone, cone_bounds=5.0)\n\n# Explicit bounds: [x_min, x_max, y_min, y_max]\ncone_hull = conehull(points, cone=cone, cone_bounds=[-10, 10, -10, 10])\n\n# Alternative format: [[x_min, y_min], [x_max, y_max]]\ncone_hull = conehull(points, cone=cone, cone_bounds=[[-10, -10], [10, 10]])\n```\n\n\n## Files\n- `_geometry.py` - Basic geometric operations like point-to-line distances and determining which side of a line points are on. Also handles sorting hull points in counterclockwise order.\n- `_conehull.py` - Implements the QuickHull algorithm for both standard and cone-constrained convex hulls. Contains the main `conehull()` function and recursive hull construction logic.\n- `_cone_intersection.py` - Transforms standard convex hulls into cone hulls by filtering halfplanes based on cone constraints. Computes intersections within configurable bounding boxes.\n- `view.py` - Visualization tools including step-by-step animations, interactive Jupyter widgets, and static plotting. Supports both automated playback and manual navigation of algorithm steps.\n- `sampler.py` - Generates test point datasets from mathematical functions. Supports parametric curves, implicit equations, and region sampling for creating diverse test cases.\n",
"bugtrack_url": null,
"license": null,
"summary": "2D convex hull algorithm with directional cone constraints and visualization tools.",
"version": "1.0.0.post3",
"project_urls": {
"Homepage": "https://github.com/Kalmander/conehull",
"Issues": "https://github.com/Kalmander/conehull/issues"
},
"split_keywords": [
"convex hull",
" computational geometry",
" quickhull",
" cone constraints",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fbec0114b3ebb5e7526164b6985f1e035d639e55cd2a2d34d9e95e065fe5280b",
"md5": "811fdaa0986982ead1055e207b95724d",
"sha256": "05a5f8ea3655ee435b101b4833ff9b0bad7465591c9ee6f3cb0e17953b622b39"
},
"downloads": -1,
"filename": "conehull-1.0.0.post3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "811fdaa0986982ead1055e207b95724d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 32327,
"upload_time": "2025-07-31T14:45:36",
"upload_time_iso_8601": "2025-07-31T14:45:36.764903Z",
"url": "https://files.pythonhosted.org/packages/fb/ec/0114b3ebb5e7526164b6985f1e035d639e55cd2a2d34d9e95e065fe5280b/conehull-1.0.0.post3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "84faa6a05c71c4847dba25b8d68c191c6c472d709e78f9955986debda0aa6693",
"md5": "63bc4a31e249644e932ffe5276935c1e",
"sha256": "69634dacd3d366784bc6c46d44e2b7ac2fa885f8dc0199b9f041810a9750698d"
},
"downloads": -1,
"filename": "conehull-1.0.0.post3.tar.gz",
"has_sig": false,
"md5_digest": "63bc4a31e249644e932ffe5276935c1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 31798,
"upload_time": "2025-07-31T14:45:37",
"upload_time_iso_8601": "2025-07-31T14:45:37.853076Z",
"url": "https://files.pythonhosted.org/packages/84/fa/a6a05c71c4847dba25b8d68c191c6c472d709e78f9955986debda0aa6693/conehull-1.0.0.post3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 14:45:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kalmander",
"github_project": "conehull",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "conehull"
}
JSON
