# `pymunk.autogeometry` Module

This module contain functions for automatic generation of geometry, for example from an image.

Example:

    >>> import pymunk
    >>> from pymunk.autogeometry import march_soft
    >>> img = [
    ...     "  xx   ",
    ...     "  xx   ",
    ...     "  xx   ",
    ...     "  xx   ",
    ...     "  xx   ",
    ...     "  xxxxx",
    ...     "  xxxxx",
    ... ]
    >>> def sample_func(point):
    ...     x = int(point[0])
    ...     y = int(point[1])
    ...     return 1 if img[y][x] == "x" else 0

    >>> pl_set = march_soft(pymunk.BB(0,0,6,6), 7, 7, .5, sample_func)
    >>> print(len(pl_set))
    2

The information in segments can now be used to create geometry, for example as a Pymunk Poly or Segment:

    >>> s = pymunk.Space()
    >>> for poly_line in pl_set:
    ...     for i in range(len(poly_line) - 1):
    ...         a = poly_line[i]
    ...         b = poly_line[i + 1]
    ...         segment = pymunk.Segment(s.static_body, a, b, 1)
    ...         s.add(segment)

class pymunk.autogeometry.PolylineSet

  Bases: `Sequence`[`List`[`Vec2d`]]

  A set of Polylines.

  Mainly intended to be used for its `collect_segment()` function when generating geometry with the `march_soft()` and `march_hard()` functions.

  __init__() → None

    Initalize a new PolylineSet

  collect_segment(v0: Tuple[float, float], v1: Tuple[float, float]) → None

    Add a line segment to a polyline set.

    A segment will either start a new polyline, join two others, or add to or loop an existing polyline. This is mostly intended to be used as a callback directly from `march_soft()` or `march_hard()`.

    Parameters:

      - v0 ((float,float)) – Start of segment

      - v1 ((float,float)) – End of segment

pymunk.autogeometry.convex_decomposition(polyline: List[Tuple[float, float]] | List[Vec2d], tolerance: float) → List[List[Vec2d]]

  Get an approximate convex decomposition from a polyline.

  Returns a list of convex hulls that match the original shape to within tolerance.

  Note

  If the input is a self intersecting polygon, the output might end up overly simplified.

  Parameters:

    - polyline ([(float,float)]) – Polyline to simplify.

    - tolerance (float) – A higher value means more error is tolerated.

  Return type:

    [(float,float)]

pymunk.autogeometry.is_closed(polyline: List[Tuple[float, float]] | List[Vec2d]) → bool

  Returns true if the first vertex is equal to the last.

  Parameters:

    polyline ([(float,float)]) – Polyline to simplify.

  Return type:

    bool

pymunk.autogeometry.march_hard(bb: BB, x_samples: int, y_samples: int, threshold: float, sample_func: Callable[[Tuple[float, float]], float]) → PolylineSet

  Trace an aliased curve of an image along a particular threshold.

  The given number of samples will be taken and spread across the bounding box area using the sampling function and context.

  Parameters:

    - bb (BB) – Bounding box of the area to sample within

    - x_samples (int) – Number of samples in x

    - y_samples (int) – Number of samples in y

    - threshold (float) – A higher value means more error is tolerated

    - sample_func (`func(point: Tuple[float, float]) -> float`) – The sample function will be called for x_samples * y_samples spread across the bounding box area, and should return a float.

  Returns:

    PolylineSet with the polylines found.

pymunk.autogeometry.march_soft(bb: BB, x_samples: int, y_samples: int, threshold: float, sample_func: Callable[[Tuple[float, float]], float]) → PolylineSet

  Trace an anti-aliased contour of an image along a particular threshold.

  The given number of samples will be taken and spread across the bounding box area using the sampling function and context.

  Parameters:

    - bb (BB) – Bounding box of the area to sample within

    - x_samples (int) – Number of samples in x

    - y_samples (int) – Number of samples in y

    - threshold (float) – A higher value means more error is tolerated

    - sample_func (`func(point: Tuple[float, float]) -> float`) – The sample function will be called for x_samples * y_samples spread across the bounding box area, and should return a float.

  Returns:

    PolylineSet with the polylines found.

pymunk.autogeometry.simplify_curves(polyline: List[Tuple[float, float]] | List[Vec2d], tolerance: float) → List[Vec2d]

  Returns a copy of a polyline simplified by using the Douglas-Peucker algorithm.

  This works very well on smooth or gently curved shapes, but not well on straight edged or angular shapes.

  Parameters:

    - polyline ([(float,float)]) – Polyline to simplify.

    - tolerance (float) – A higher value means more error is tolerated.

  Return type:

    [(float,float)]

pymunk.autogeometry.simplify_vertexes(polyline: List[Tuple[float, float]] | List[Vec2d], tolerance: float) → List[Vec2d]

  Returns a copy of a polyline simplified by discarding “flat” vertexes.

  This works well on straight edged or angular shapes, not as well on smooth shapes.

  Parameters:

    - polyline ([(float,float)]) – Polyline to simplify.

    - tolerance (float) – A higher value means more error is tolerated.

  Return type:

    [(float,float)]

pymunk.autogeometry.to_convex_hull(polyline: List[Tuple[float, float]] | List[Vec2d], tolerance: float) → List[Vec2d]

  Get the convex hull of a polyline as a looped polyline.

  Parameters:

    - polyline ([(float,float)]) – Polyline to simplify.

    - tolerance (float) – A higher value means more error is tolerated.

  Return type:

    [(float,float)]