Projections¶

Constructors¶

detroit.geo_projection(project: RawProjection) → Projection¶

Constructs a new projection from the specified raw projection project. The project function takes the longitude and latitude of a given point in radians, often referred to as lambda (\(\lambda\)) and phi (\(\phi\)), and returns a two-element array [x, y] representing its unit projection. The project function does not need to scale or translate the point, as these are applied automatically by projection.scale, projection.translate, and projection.center. Likewise, the project function does not need to perform any spherical rotation, as projection.rotate is applied prior to projection.

Parameters:: project (RawProjection) – Projection object
Returns:: Projection object
Return type:: Projection

detroit.geo_projection_mutator(project: Callable[[...], RawProjection]) → Callable[[...], Projection]¶

Constructs a new projection from the specified raw projection factory and returns a mutate function to call whenever the raw projection changes. The factory must return a raw projection. The returned mutate function returns the wrapped projection. For example, a conic projection typically has two configurable parallels.

Parameters:: project (Callable[..., RawProjection]) – Function which generates a projection object
Returns:: Projection object
Return type:: Callable[…, Projection]

Projection classes¶

class detroit.geo.common.RawProjection(*args, **kwargs)¶

Raw projections are point transformation functions that are used to implement custom projections; they typically passed to geo_projection or geo_projection_mutator. They are exposed here to facilitate the derivation of related projections. Raw projections take spherical coordinates [lambda, phi] in radians (not degrees!) and return a point [x, y], typically in the unit square centered around the origin.

__call__(lambda_: float, phi: float) → tuple[float, float]¶

Projects the specified point [lambda, phi] in radians, returning a new point [x, y] in unitless coordinates.

Parameters:

lambda (float) – \(\lambda\) value
phi (float) – \(\phi\) value

Returns:

New point

Return type:

Point2D

invert(x: float, y: float) → tuple[float, float]¶

Optional method: the inverse of the projection.

Parameters:

x (float) – x value
y (float) – y value

Returns:

[lambda, phi] coordinates in radians

Return type:

Point2D

class detroit.geo.common.Projection¶

abstractmethod __call__(point: tuple[float, float]) → tuple[float, float]¶

Returns a new array [x, y] (typically in pixels) representing the projected point of the given point. The point must be specified as a two-element array [longitude, latitude] in degrees. May return None if the specified point has no defined projected position, such as when the point is outside the clipping bounds of the projection.

Parameters:: point (Point2D) – Point [longitude, latitude]
Returns:: New projected point [x, y]
Return type:: Point2D

abstractmethod invert(point: tuple[float, float]) → tuple[float, float]¶

Returns a new array [longitude, latitude] in degrees representing the unprojected point of the given projected point. The point must be specified as a two-element array [x, y] (typically in pixels). May return null if the specified point has no defined projected position, such as when the point is outside the clipping bounds of the projection.

This method is only defined on invertible projections.

Parameters:: point (Point2D) – 2D point where coordinates are in pixels
Returns:: 2D point where coordinates are in degrees
Return type:: Point2D

abstractmethod stream(stream: PolygonStream) → PolygonStream¶

Returns a projection stream for the specified output stream. Any input geometry is projected before being streamed to the output stream. A typical projection involves several geometry transformations: the input geometry is first converted to radians, rotated on three axes, clipped to the small circle or cut along the antimeridian, and lastly projected to the plane with adaptive resampling, scale and translation.

Parameters:: stream (PolygonStream) – Stream object
Returns:: Modified stream object
Return type:: PolygonStream

set_preclip(preclip: Callable[[PolygonStream], PolygonStream]) → Projection¶

If preclip is specified, sets the projection’s spherical clipping to the specified function and returns the projection; preclip is a function that takes a projection stream and returns a clipped stream.

Parameters:: preclip (Callable[[PolygonStream], PolygonStream]) – Preclip function
Returns:: Itself
Return type:: Projection

set_postclip(postclip: Callable[[PolygonStream], PolygonStream]) → Projection¶

If postclip is specified, sets the projection’s Cartesian clipping to the specified function and returns the projection; postclip is a function that takes a projection stream and returns a clipped stream.

Parameters:: postclip (Callable[[PolygonStream], PolygonStream]) – Postclip function
Returns:: Itself
Return type:: Projection

set_clip_angle(clip_angle: float | None = None) → Projection¶

If angle is specified, sets the projection’s clipping circle radius to the specified angle in degrees and returns the projection. If angle is None, switches to antimeridian cutting rather than small-circle clipping. If angle is not specified, returns the current clip angle which defaults to None. Small-circle clipping is independent of viewport clipping via projection.clipExtent.

Parameters:: clip_angle (float | None) – Clip angle
Returns:: Itself
Return type:: Projection

set_clip_extent(clip_extent: tuple[tuple[float, float], tuple[float, float]] | None = None) → Projection¶

If extent is specified, sets the projection’s viewport clip extent to the specified bounds in pixels and returns the projection. The extent bounds are specified as an array \([[x_0, y_0], [x_1, y_1]]\), where \(x_0\) is the left-side of the viewport, \(y_0\) is the top, \(x_1\) is the right and \(y_1\) is the bottom. If extent is None, no viewport clipping is performed. If extent is not specified, returns the current viewport clip extent which defaults to None. Viewport clipping is independent of small-circle clipping via projection.clipAngle.

Parameters:: clip_extent (tuple[Point2D, Point2D] | None)
Returns:: Itself
Return type:: Projection

abstractmethod scale(k: float) → Projection¶

If scale is specified, sets the projection’s scale factor to the specified value and returns the projection. The scale factor corresponds linearly to the distance between projected points; however, absolute scale factors are not equivalent across projections.

Parameters:: k (float) – Scale factor
Returns:: Itself
Return type:: Projection

abstractmethod translate(translation: tuple[float, float]) → Projection¶

If translate is specified, sets the projection’s translation offset to the specified two-element array [tx, ty] and returns the projection. The translation offset determines the pixel coordinates of the projection’s center. The default translation offset places \([0°,0°]\) at the center of a \(960 \times 500\) area.

Parameters:: translation (Vec2D) – Translation 2D vector
Returns:: Itself
Return type:: Projection

rotate(angles: tuple[float, float] | tuple[float, float, float]) → Projection¶

If angles is specified, sets the projection’s three-axis spherical rotation to the specified value, which must be a two- or three-element array of numbers \([\lambda, \phi, \gamma]\) specifying the rotation angles in degrees about each spherical axis. (These correspond to yaw, pitch and roll).

Parameters:: angles (tuple[float, float] | tuple[float, float, float]) – \([\lambda, \phi, \gamma]\) values or \([\lambda, \phi]\) values
Returns:: Itself
Return type:: Projection

set_center(center: tuple[float, float]) → Projection¶

If center is specified, sets the projection’s center to the specified center, a two-element array of [longitude, latitude] in degrees and returns the projection.

Parameters:: center (Point2D) – Center point
Returns:: Itself
Return type:: Projection

set_angle(angle: float) → Projection¶

If angle is specified, sets the projection’s post-projection planar rotation angle to the specified angle in degrees and returns the projection.

Parameters:: angle (float) – Angle value
Returns:: Itself
Return type:: Projection

set_reflect_x(reflect_x: bool) → Projection¶

If reflect is specified, sets whether or not the x-dimension is reflected (negated) in the output. This can be useful to display sky and astronomical data with the orb seen from below: right ascension (eastern direction) will point to the left when North is pointing up.

Parameters:: reflect_x (bool) – Boolean value
Returns:: Itself
Return type:: Projection

set_reflect_y(reflect_y: bool) → Projection¶

If reflect is specified, sets whether or not the y-dimension is reflected (negated) in the output. This is especially useful for transforming from standard spatial reference systems, which treat positive y as pointing up, to display coordinate systems such as Canvas and SVG, which treat positive y as pointing down.

Parameters:: reflect_y (bool) – Boolean value
Returns:: Itself
Return type:: Projection

abstractmethod set_precision(precision: float) → Projection¶

If precision is specified, sets the threshold for the projection’s adaptive resampling to the specified value in pixels and returns the projection. This value corresponds to the Douglas–Peucker distance.

Parameters:: precision (float) – Precision value
Returns:: Itself
Return type:: Projection

abstractmethod fit_extent(extent: tuple[tuple[float, float], tuple[float, float]], obj: dict[str, Any]) → Projection¶

Sets the projection’s scale and translate to fit the specified GeoJSON object in the center of the given extent. The extent is specified as an array \([[x_0, y_0], [x_1, y_1]]\), where \(x_0\) is the left side of the bounding box, \(y_0\) is the top, \(x_1`₁ is the right and :math:`y_1\) is the bottom. Returns the projection.

Any clip extent is ignored when determining the new scale and translate. The precision used to compute the bounding box of the given object is computed at an effective scale of 150.

Parameters:

extent (tuple[Point2D, Point2D]) – Extent values
obj (GeoJSON) – GeoJSON object

Returns:

Itself

Return type:

Projection

abstractmethod fit_size(size: tuple[float, float], obj: dict[str, Any]) → Projection¶

A convenience method for projection.fit_extent where the top-left corner of the extent is [0, 0].

Parameters:

size (Point2D) – Size values
obj (GeoJSON) – GeoJSON object

Returns:

Itself

Return type:

Projection

abstractmethod fit_width(width: float, obj: dict[str, Any]) → Projection¶

A convenience method for projection.fit_size where the height is automatically chosen from the aspect ratio of object and the given constraint on width.

Parameters:

width (float) – Width value
obj (GeoJSON) – GeoJSON object

Returns:

Itself

Return type:

Projection

abstractmethod fit_height(height: float, obj: dict[str, Any]) → Projection¶

A convenience method for projection.fit_size where the width is automatically chosen from the aspect ratio of object and the given constraint on height.

Parameters:

height (float) – Height value
obj (GeoJSON) – GeoJSON object

Returns:

Itself

Return type:

Projection

Clipping functions¶

detroit.geo_clip_antimeridian(sink: PolygonStream) → Clip¶

A clipping function which transforms a stream such that geometries (lines or polygons) that cross the antimeridian line are cut in two, one on each side. Typically used for pre-clipping.

Returns:: Clipping function
Return type:: Callable[[PolygonStream], ClipRectangle]

detroit.geo_clip_circle(angle: float) → Callable[[PolygonStream], Clip]¶

Generates a clipping function which transforms a stream such that geometries are bounded by a small circle of radius angle around the projection’s center. Typically used for pre-clipping.

Parameters:: angle (float) – Radius Angle value around the projection’s center
Returns:: Clipping function
Return type:: Callable[[PolygonStream], Clip]

detroit.geo_clip_rectangle(x0: float, y0: float, x1: float, y1: float) → Callable[[PolygonStream], ClipRectangle]¶

Generates a clipping function which transforms a stream such that geometries are bounded by a rectangle of coordinates \([[x_0, y_0], [x_1, y_1]]\). Typically used for post-clipping.

Parameters:

x0 (float) – \(x_0\) coordinate of the rectangle
y0 (float) – \(y_0\) coordinate of the rectangle
x1 (float) – \(x_1\) coordinate of the rectangle
y1 (float) – \(y_1\) coordinate of the rectangle

Returns:

Clipping function

Return type:

Callable[[PolygonStream], ClipRectangle]

Transform function¶

detroit.geo_transform(methods: dict[str, Callable[[...], ...]]) → GeoTransform¶

Defines an arbitrary transform using the methods defined on the specified methods object. Any undefined methods will use pass-through methods that propagate inputs to the output stream.

Parameters:: methods (dict[str, Callable[..., ...]]) – Methods applied on a stream object
Returns:: Class which holds the passed methods
Return type:: GeoTransform

class detroit.geo.transform.GeoTransform(methods: dict[str, Callable[[...], ...]])¶

Defines an arbitrary transform using the methods defined on the specified methods object. Any undefined methods will use pass-through methods that propagate inputs to the output stream.

Parameters:: methods (dict[str, Callable[..., ...]]) – Methods applied on a stream object

stream() → GeoTransformer¶

Passes methods to a new class which transforms the methods of a stream object given the methods and returns it.

Returns:: Callable object which modifies the behavior of a stream object
Return type:: GeoTransformer

class detroit.geo.transform.GeoTransformer(methods: dict[str, Callable[[...], ...]])¶

Transform a stream object given methods

Parameters:: methods (dict[str, Callable[..., ...]]) – Methods applied on a stream object

__call__(stream: PolygonStream) → TransformStream¶

Creates a new TransformStream with the argument stream and updates its methods.

Parameters:: stream (PolygonStream) – Stream object
Returns:: Transformed stream
Return type:: TransformStream

__str__()¶: Return str(self).

class detroit.geo.transform.TransformStream(stream: PolygonStream)¶

Default class where methods don’t affect the behavior of the passed stream object if they are not updated.

Parameters:: stream (PolygonStream) – Stream object

point(x: float, y: float)¶

Calls the stream point method

Parameters:

x (float) – x value
y (float) – y value

sphere()¶: Calls the stream sphere method

line_start()¶: Calls the stream line_start method

line_end()¶: Calls the stream line_end method

polygon_start()¶: Calls the stream polygon_start method

polygon_end()¶: Calls the stream polygon_end method

Contents: