tessl/pypi-colour-science

Comprehensive Python library providing algorithms and datasets for colour science computations, including chromatic adaptation, colour appearance models, colorimetry, and spectral analysis.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Geometric Computations

Name: tessl/pypi-colour-science
Author: tessl

Geometric computation functions including ellipse fitting, line segment intersections, primitive shape generation, hull sectioning, and vertex calculations for color space visualization and analysis.

Capabilities

Ellipse Fitting and Analysis

Functions for fitting ellipses to data points and working with elliptical representations.

def ellipse_fitting(coefficients: ArrayLike, method: str = "Halir 1998") -> NDArray:
    """
    Fit an ellipse to given coefficients using specified method.
    
    Parameters:
    - coefficients: ellipse coefficients or data points
    - method: fitting method
        - "Halir 1998" (default): Halir and Flusser (1998) algebraic ellipse fitting
    
    Returns:
    Fitted ellipse parameters
    """

def ellipse_coefficients_general_form(coefficients: ArrayLike) -> NDArray:
    """
    Convert ellipse coefficients to general form Ax² + Bxy + Cy² + Dx + Ey + F = 0.
    
    Parameters:
    - coefficients: ellipse coefficients in canonical form
    
    Returns:
    General form coefficients [A, B, C, D, E, F]
    """

def ellipse_coefficients_canonical_form(coefficients: ArrayLike) -> NDArray:
    """
    Convert ellipse coefficients to canonical form parameters.
    
    Parameters:
    - coefficients: ellipse coefficients in general form
    
    Returns:
    Canonical form parameters [center_x, center_y, semi_major, semi_minor, angle]
    """

def point_at_angle_on_ellipse(coefficients: ArrayLike, angle: float) -> NDArray:
    """
    Calculate point coordinates at given angle on ellipse.
    
    Parameters:
    - coefficients: ellipse coefficients in canonical form
    - angle: angle in radians
    
    Returns:
    Point coordinates [x, y] on ellipse
    """

# Method collection for ellipse fitting
ELLIPSE_FITTING_METHODS: Dict[str, Callable]

Line Segment Operations

Functions for working with line segments including intersection calculations and extensions.

def intersect_line_segments(l_1: ArrayLike, l_2: ArrayLike) -> LineSegmentsIntersections_Specification:
    """
    Calculate intersection points between two line segments.
    
    Parameters:
    - l_1: first line segment endpoints as array [[x1, y1], [x2, y2]]
    - l_2: second line segment endpoints as array [[x1, y1], [x2, y2]]
    
    Returns:
    LineSegmentsIntersections_Specification with intersection data
    """

def extend_line_segment(segment: ArrayLike, distance: float) -> NDArray:
    """
    Extend line segment by specified distance.
    
    Parameters:
    - segment: line segment endpoints [[x1, y1], [x2, y2]]
    - distance: extension distance
    
    Returns:
    Extended line segment endpoints
    """

class LineSegmentsIntersections_Specification:
    """
    Specification class for line segment intersection results.
    
    Attributes:
    - xy: intersection point coordinates
    - intersect: whether segments intersect
    - parallel: whether segments are parallel
    - collinear: whether segments are collinear
    """
    xy: NDArray
    intersect: bool
    parallel: bool
    collinear: bool

Primitive Shape Generation

Functions for generating geometric primitives used in color space visualizations.

def primitive(method: str = "cube", **kwargs) -> NDArray:
    """
    Generate geometric primitive vertices using specified method.
    
    Parameters:
    - method: primitive type
        - "cube" (default): unit cube vertices
        - "grid": rectangular grid
    - **kwargs: method-specific parameters
    
    Returns:
    Primitive vertex coordinates
    """

def primitive_grid(width: int = 16, height: int = 16, depth: int = 16) -> NDArray:
    """
    Generate rectangular grid primitive.
    
    Parameters:
    - width: grid width resolution
    - height: grid height resolution  
    - depth: grid depth resolution
    
    Returns:
    Grid vertex coordinates as ndarray shape (width*height*depth, 3)
    """

def primitive_cube() -> NDArray:
    """
    Generate unit cube primitive vertices.
    
    Returns:
    Cube vertex coordinates as ndarray shape (8, 3)
    """

# Method collection for primitive generation
PRIMITIVE_METHODS: Dict[str, Callable]

# Axis mapping for plane-to-axis conversions
MAPPING_PLANE_TO_AXIS: Dict[str, int]

Primitive Vertices Generation

Functions for generating vertices for various primitive shapes with different backends.

def primitive_vertices(method: str = "cube", **kwargs) -> NDArray:
    """
    Generate primitive vertices using specified method.
    
    Parameters:
    - method: vertex generation method
        - "cube": cube vertices
        - "grid": grid vertices
        - "quad_mpl": matplotlib quad vertices
        - "sphere": sphere vertices
    - **kwargs: method-specific parameters
    
    Returns:
    Vertex coordinates
    """

def primitive_vertices_cube_mpl(**kwargs) -> NDArray:
    """
    Generate cube vertices for matplotlib visualization.
    
    Parameters:
    - **kwargs: additional parameters for cube generation
    
    Returns:
    Cube vertices formatted for matplotlib
    """

def primitive_vertices_grid_mpl(width: int = 16, height: int = 16, **kwargs) -> NDArray:
    """
    Generate grid vertices for matplotlib visualization.
    
    Parameters:
    - width: grid width resolution
    - height: grid height resolution
    - **kwargs: additional parameters
    
    Returns:
    Grid vertices formatted for matplotlib
    """

def primitive_vertices_quad_mpl(**kwargs) -> NDArray:
    """
    Generate quadrilateral vertices for matplotlib visualization.
    
    Parameters:
    - **kwargs: additional parameters for quad generation
    
    Returns:
    Quad vertices formatted for matplotlib
    """

def primitive_vertices_sphere(segments: int = 16, **kwargs) -> NDArray:
    """
    Generate sphere vertices.
    
    Parameters:
    - segments: number of spherical segments
    - **kwargs: additional parameters
    
    Returns:
    Sphere vertex coordinates
    """

# Method collection for primitive vertices
PRIMITIVE_VERTICES_METHODS: Dict[str, Callable]

Hull Section Analysis

Functions for analyzing hull sections in geometric data.

def hull_section(points: ArrayLike, axis: str = "z", origin: float = 0, 
                normalise: bool = True) -> NDArray:
    """
    Calculate hull section of points along specified axis.
    
    Parameters:
    - points: point coordinates as ndarray
    - axis: sectioning axis ("x", "y", or "z")
    - origin: section plane position along axis
    - normalise: whether to normalise coordinates
    
    Returns:
    Hull section boundary points
    """

Usage Examples

Ellipse Fitting

import colour
import numpy as np

# Generate sample ellipse data points
angles = np.linspace(0, 2*np.pi, 20)
a, b = 5, 3  # semi-major and semi-minor axes
x = a * np.cos(angles) + np.random.normal(0, 0.1, 20)
y = b * np.sin(angles) + np.random.normal(0, 0.1, 20)
points = np.column_stack([x, y])

# Fit ellipse to points
ellipse_params = colour.ellipse_fitting(points, method="Halir 1998")
print(f"Ellipse parameters: {ellipse_params}")

# Get points on fitted ellipse
test_angles = np.array([0, np.pi/4, np.pi/2])
ellipse_points = [colour.point_at_angle_on_ellipse(ellipse_params, angle) 
                  for angle in test_angles]
print(f"Points on ellipse: {ellipse_points}")

Line Segment Intersections

import colour
import numpy as np

# Define two line segments
line1 = np.array([[0, 0], [4, 4]])  # Diagonal line
line2 = np.array([[0, 4], [4, 0]])  # Opposite diagonal

# Find intersection
intersection = colour.intersect_line_segments(line1, line2)
print(f"Intersection point: {intersection.xy}")
print(f"Do they intersect? {intersection.intersect}")
print(f"Are they parallel? {intersection.parallel}")

# Extend a line segment
extended_line = colour.extend_line_segment(line1, 2.0)
print(f"Extended line: {extended_line}")

Primitive Generation

import colour
import numpy as np

# Generate cube vertices
cube_vertices = colour.primitive("cube")
print(f"Cube vertices shape: {cube_vertices.shape}")
print(f"Cube vertices:\n{cube_vertices}")

# Generate grid primitive
grid_vertices = colour.primitive_grid(width=4, height=4, depth=4)
print(f"Grid vertices shape: {grid_vertices.shape}")

# Generate sphere vertices
sphere_vertices = colour.primitive_vertices("sphere", segments=8)
print(f"Sphere vertices shape: {sphere_vertices.shape}")

Visualization Primitives

import colour
import numpy as np

# Generate matplotlib-compatible primitives
quad_vertices = colour.primitive_vertices_quad_mpl()
cube_vertices_mpl = colour.primitive_vertices_cube_mpl()
grid_vertices_mpl = colour.primitive_vertices_grid_mpl(width=8, height=8)

print(f"Quad vertices for matplotlib: {quad_vertices.shape}")
print(f"Cube vertices for matplotlib: {cube_vertices_mpl.shape}")
print(f"Grid vertices for matplotlib: {grid_vertices_mpl.shape}")

Hull Section Analysis

import colour
import numpy as np

# Generate random 3D points
points = np.random.random((100, 3)) * 10

# Calculate hull sections along different axes
hull_z = colour.hull_section(points, axis="z", origin=5.0)
hull_x = colour.hull_section(points, axis="x", origin=7.5, normalise=False)

print(f"Z-axis hull section shape: {hull_z.shape}")
print(f"X-axis hull section shape: {hull_x.shape}")

Types

from colour.hints import ArrayLike, NDArray, Dict, Callable
from typing import NamedTuple

# Specification classes  
class LineSegmentsIntersections_Specification(NamedTuple):
    xy: NDArray
    intersect: bool
    parallel: bool
    collinear: bool

# Method collections type
GeometryMethodCollection = Dict[str, Callable]

# Axis mapping type
AxisMapping = Dict[str, int]

Imports

# Ellipse operations
from colour.geometry import (
    ellipse_fitting, ellipse_coefficients_general_form,
    ellipse_coefficients_canonical_form, point_at_angle_on_ellipse,
    ELLIPSE_FITTING_METHODS
)

# Line operations  
from colour.geometry import (
    intersect_line_segments, extend_line_segment,
    LineSegmentsIntersections_Specification
)

# Primitive generation
from colour.geometry import (
    primitive, primitive_grid, primitive_cube,
    primitive_vertices, PRIMITIVE_METHODS, PRIMITIVE_VERTICES_METHODS
)

# Hull analysis
from colour.geometry import hull_section

# Alternative imports from main package
from colour import (
    ellipse_fitting, intersect_line_segments, primitive,
    primitive_vertices, hull_section
)

Install with Tessl CLI