Zoom¶

detroit_live.zoom(extra_nodes: list[Element] | None = None)¶

Creates a new zoom behavior. The returned behavior, zoom, is both an object and a function, and is typically applied to selected elements via Selection.call.

Parameters:: extra_nodes (list[etree.Element] | None) – Extra nodes to update when the listener is called

class detroit_live.zoom.zoom.Zoom(extra_nodes: list[Element] | None = None)¶

Creates a new zoom behavior. The returned behavior, zoom, is both an object and a function, and is typically applied to selected elements via Selection.call.

Parameters:: extra_nodes (list[etree.Element] | None) – Extra nodes to update when the listener is called

__call__(selection: LiveSelection)¶

Applies this zoom behavior to the specified selection, binding the necessary event listeners to allow panning and zooming, and initializing the zoom transform on each selected element to the identity transform if not already defined.

Parameters:: selection (LiveSelection) – Selection

transform(collection: LiveSelection, transform: Callable[[Element, T, int, list[Element]], Transform] | Transform, point: tuple[float, float], event: Event)¶

Sets the current zoom transform of the selected elements to the specified transform, instantaneously emitting start, zoom and end events.

Parameters:

collection (LiveSelection) – Selection
transform (EtreeFunction[T, Transform] | Transform) – Transform object or function which returns a tranform object
point (tuple[float, float]) – 2D point
event (Event) – Event

scale_by(selection: LiveSelection, k: Callable[[Element, T, int, list[Element]], float] | float, p: tuple[float, float], event: Event)¶

If selection is a selection, scales the current zoom transform of the selected elements by k, such that the new \(k_1 = k_0 k\). The reference point p does move. If p is not specified, it defaults to the center of the viewport extent. If selection is a transition, defines a “zoom” tween translating the current transform. This method is a convenience method for zoom.transform. The k scale factor may be specified either as a number or a function that returns a number; similarly the p point may be specified either as a two-element array \([p_x, p_y]\) or a function. If a function, it is invoked for each selected element, being passed the current datum d and index i, with the this context as the current DOM element.

Parameters:

selection (LiveSelection) – Selection
k (EtreeFunction[T, float] | float) – Scale factor or function which returns the scale factor
p (tuple[float, float]) – 2D point
event (Event) – Event

scale_to(selection: LiveSelection, k: Callable[[Element, T, int, list[Element]], float] | float, p: Callable[[Element, T, int, list[Element]], tuple[float, float]] | tuple[float, float] | None, event: Event)¶

If selection is a selection, scales the current zoom transform of the selected elements by k, such that the new \(k_1 = k\). The reference point p does move. If p is not specified, it defaults to the center of the viewport extent. If selection is a transition, defines a “zoom” tween translating the current transform. This method is a convenience method for zoom.transform. The k scale factor may be specified either as a number or a function that returns a number; similarly the p point may be specified either as a two-element array \([p_x, p_y]\) or a function. If a function, it is invoked for each selected element, being passed the current datum d and index i, with the this context as the current DOM element.

Parameters:

selection (LiveSelection) – Selection
k (EtreeFunction[T, float] | float) – Scale factor or function which returns the scale factor
p (EtreeFunction[T, tuple[float, float]] | tuple[float, float] | None) – 2D point or function which returns a 2D point
event (Event) – Event

translate_by(selection: LiveSelection, x: Callable[[Element, T, int, list[Element]], float] | float, y: Callable[[Element, T, int, list[Element]], float] | float, event: Event)¶

If selection is a selection, translates the current zoom transform of the selected elements by x and y, such that the new \(t_{x1} = t_{x0} + kx\) and \(t_{y1} = t_{y0} + ky\). If selection is a transition, defines a “zoom” tween translating the current transform. This method is a convenience method for zoom.transform. The x and y translation amounts may be specified either as numbers or as functions that return numbers. If a function, it is invoked for each selected element, being passed the current datum d and index i, with the this context as the current DOM element.

Parameters:

selection (LiveSelection) – Selection
x (EtreeFunction[T, float] | float) – x-coordinate translation value or function which returns the x-coordinate translation value
y (EtreeFunction[T, float] | float) – y-coordinate translation value or function which returns the y-coordinate translation value
event (Event) – Event

translate_to(selection: LiveSelection, x: Callable[[Element, T, int, list[Element]], float] | float, y: Callable[[Element, T, int, list[Element]], float] | float, p: Callable[[Element, T, int, list[Element]], tuple[float, float]] | tuple[float, float] | None, event: Event)¶

Parameters:

selection (LiveSelection) – Selection
x (EtreeFunction[T, float] | float) – x-coordinate translation value or function which returns the x-coordinate translation value
y (EtreeFunction[T, float] | float) – y-coordinate translation value or function which returns the y-coordinate translation value
p (EtreeFunction[T, tuple[float, float]] | tuple[float, float] | None) – 2D point or function which returns a 2D point
event (Event) – Event

on(typenames: str, callback: Callable[[...], None]) → Zoom¶

Sets the event listener for the specified typenames and returns the zoom behavior. If an event listener was already registered for the same type and name, the existing listener is removed before the new listener is added. If listener is None, removes the current event listeners for the specified typenames, if any. If listener is not specified, returns the first currently-assigned listener matching the specified typenames, if any. When a specified event is dispatched, each listener will be invoked with the same context and arguments as selection.on listeners: the current event (event) and datum d, with the this context as the current DOM element.

The typenames is a string containing one or more typename separated by whitespace. Each typename is a type, optionally followed by a period (.) and a name, such as zoom.foo and zoom.bar; the name allows multiple listeners to be registered for the same type. The type must be one of the following:

"start" - after zooming begins (such as on mousedown).
"zoom" - after a change to the zoom transform (such as on mousemove).
"end" - after zooming ends (such as on mouseup ).

Parameters:

typenames (str) – Typenames
callback (Callable[..., None]) – Callback function

Returns:

Itself

Return type:

Zoom

set_wheel_delta(wheel_delta: Callable[[Event], float] | float) → Zoom¶

Sets the wheel delta function to the specified function and returns the zoom behavior.

Parameters:: wheel_delta (Callable[[Event], float] | float) – Wheel delta function or constant value
Returns:: Itself
Return type:: Zoom

set_filter(filter_func: Callable[[Element, T | None, list[Element]], bool] | bool) → Zoom¶

Sets the filter to the specified function and returns the zoom behavior.

The filter is passed the current event (event) and datum d, with the this context as the current DOM element. If the filter returns falsey, the initiating event is ignored and no zoom gestures are started. Thus, the filter determines which input events are ignored. The default filter ignores mousedown events on secondary buttons, since those buttons are typically intended for other purposes, such as the context menu.

Parameters:: filter_func (EventFunction[T | None, bool] | bool) – Filter function
Returns:: Itself
Return type:: Zoom

set_touchable(touchable: Callable[[LiveSelection], Callable[[Element, T | None, list[Element]], bool]] | Callable[[...], bool]) → Zoom¶

Sets the touch support detector to the specified function and returns the zoom behavior.

Touch event listeners are only registered if the detector returns truthy for the corresponding element when the zoom behavior is applied. The default detector works well for most browsers that are capable of touch input, but not all; Chrome’s mobile device emulator, for example, fails detection.

Parameters:: touchable (Callable[[LiveSelection], EventFunction[T | None, bool]] | Callable[..., bool]) – Function which takes a selection and returns a touchable function. Therefore, the wrapped function (touchable function) can access to the selection.
Returns:: Itself
Return type:: Zoom

set_extent(extent: Callable[[Element], tuple[tuple[float, float], tuple[float, float]]] | tuple[tuple[float, float], tuple[float, float]]) → Zoom¶

If extent is specified, sets the viewport extent to the specified array of points \([[x_0, y_0], [x_1, y_1]]\), where \([x_0, y_0]\) is the top-left corner of the viewport and \([x_1, y_1]\) is the bottom-right corner of the viewport, and returns this zoom behavior. The extent may also be specified as a function which returns such an array; if a function, it is invoked for each selected element, being passed the current datum d, with the this context as the current DOM element.

The viewport extent affects several functions: the center of the viewport remains fixed during changes by zoom.scale_by and zoom.scale_to; the viewport center and dimensions affect the path chosen by interpolate_zoom; and the viewport extent is needed to enforce the optional translate extent.

Parameters:: extent (Callable[[etree.Element], Extent] | Extent) – Array of points \([[x_0, y_0], [x_1, y_1]]\) or function which returns an array of points \([[x_0, y_0], [x_1, y_1]]\)
Returns:: Itself
Return type:: Zoom

set_scale_extent(scale_extent: tuple[float, float]) → Zoom¶

If extent is specified, sets the scale extent to the specified array of numbers \([k_0, k_1]\) where k0 is the minimum allowed scale factor and \(k_1\) is the maximum allowed scale factor, and returns this zoom behavior. The scale extent restricts zooming in and out. It is enforced on interaction and when using zoom.scale_by, zoom.scale_to and zoom.translate_by; however, it is not enforced when using zoom.transform to set the transform explicitly.

Parameters:: scale_extent (tuple[float, float]) – Array of numbers \([k_0, k_1]\)
Returns:: Itself
Return type:: Zoom

set_translate_extent(translate_extent: tuple[tuple[float, float], tuple[float, float]]) → Zoom¶

If extent is specified, sets the translate extent to the specified array of points \([[x_0, y_0], [x_1, y_1]]\), where \([x_0, y_0]\) is the top-left corner of the world and \([x_1, y_1]\) is the bottom-right corner of the world, and returns this zoom behavior. The translate extent restricts panning, and may cause translation on zoom out. It is enforced on interaction and when using zoom.scale_by, zoom.scale_to and zoom.translate_by; however, it is not enforced when using zoom.transform to set the transform explicitly.

Parameters:: translate_extent (Extent) – Array of points \([[x_0, y_0], [x_1, y_1]]\)
Returns:: Itself
Return type:: Zoom

set_constrain(constrain: Callable[[Transform, tuple[tuple[float, float], tuple[float, float]], tuple[tuple[float, float], tuple[float, float]]], Transform]) → Zoom¶

Sets the transform constraint function to the specified function and returns the zoom behavior.

The constraint function must return a Transform object given the current transform, viewport extent and translate extent. The default implementation attempts to ensure that the viewport extent does not go outside the translate extent.

Parameters:: constrain (Callable[[Transform, Extent, Extent], Transform]) – Constrain function
Returns:: Itself
Return type:: Zoom

set_duration(duration: int | float) → Zoom¶

Sets the duration for zoom transitions on double-click and double-tap to the specified number of milliseconds and returns the zoom behavior.

Parameters:: duration (int | float) – Duration in milliseconds
Returns:: Itself
Return type:: Zoom

set_interpolate(interpolation: Callable[[float, float], Callable[[float], float]]) → Zoom¶

Sets the interpolation factory for zoom transitions to the specified function.

Parameters:: interpolation (Callable[[float, float], Callable[[float], float]]) – Interpolation function
Returns:: Itself
Return type:: Zoom

set_click_distance(click_distance: int | float) → Zoom¶

Sets the maximum distance that the mouse can move between mousedown and mouseup that will trigger a subsequent click event. If at any point between mousedown and mouseup the mouse is greater than or equal to distance from its position on mousedown, the click event following mouseup will be suppressed.

Parameters:: click_distance (int | float) – Click distance value
Returns:: Itself
Return type:: Zoom

set_tap_distance(tap_distance: int | float) → Zoom¶

Sets the maximum distance that a double-tap gesture can move between first touchstart and second touchend that will trigger a subsequent double-click event.

Parameters:: tap_distance (int | float) – Tap distance value
Returns:: Itself
Return type:: Zoom

Zoom Transform¶

detroit_live.zoom_transform(node: Element) → Transform¶

Returns the current transform for the specified node. Note that node should typically be a DOM element, not a selection. (A selection may consist of multiple nodes, in different states, and this function only returns a single transform.)

Parameters:: node (etree.Element) – Node element
Returns:: Transform object
Return type:: Transform

detroit_live.ZoomTransform¶: alias of Transform

detroit_live.zoom_identity¶: alias of <detroit_live.zoom.transform.Transform object>

Note

d3.zoom_identity is equivalent to d3.ZoomTransform(1, 0, 0)

class detroit_live.zoom.transform.Transform(k: float, x: float, y: float)¶

Transform object with scale k and translation (x, y)

Parameters:

k (float) – Scale factor
x (float) – X-coordinate translation
y (float) – Y-coordinate translation

k¶

Scale factor

Type:: float

x¶

X-coordinate translation

Type:: float

y¶

Y-coordinate translation

Type:: float

Examples

>>> identity = d3.ZoomTransform(1, 0, 0)
>>> identity == d3.zoom_identity
True

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

Returns the transformation of the specified point which is a two-element array of numbers [x, y]. The returned point is equal to \([x \ cdot k + t_x, y \cdot k + t_y]\).

Parameters:: point (tuple[float, float]) – Point to transform
Returns:: Transformed point
Return type:: tuple[float, float]

__eq__(o: Any) → bool¶

Checks if the other object is the same as itself.

Parameters:: o (Any) – Other object
Returns:: True if the o object is the same as self
Return type:: bool

scale(k: float) → Transform¶

Returns a transform whose scale k`₁ is equal to :math:`k_0 cdot k, where \(k_0\) is this transform’s scale.

Parameters:: k (float) – Scale factor
Returns:: New transformation
Return type:: Transform

translate(x: float, y: float) → Transform¶

Returns a transform whose translation \(t_{x_1}\) and \(t_{y_1}\) is equal to \(t_{x_0} + t_k x\) and \(t_{y_0} + t_k y\), where \(t_{x_0}\) and \(t_{y_0}\) is this transform’s translation and \(t_k\) is this transform’s scale.

Parameters:

x (float) – X-coordinate translation
y (float) – Y-coordinate translation

Returns:

New transformation

Return type:

Transform

apply_x(x: float) → float¶

Returns the transformation of the specified x-coordinate, \(x \cdot k + t_x\).

Parameters:: x (float) – X-coordinate point
Returns:: Result of the transformation
Return type:: float

apply_y(y: float) → float¶

Returns the transformation of the specified y-coordinate, \(y \cdot k + t_y\).

Parameters:: y (float) – Y-coordinate point
Returns:: Result of the transformation
Return type:: float

invert(location: tuple[float, float]) → tuple[float, float]¶

Returns the inverse transformation of the specified point which is a two-element array of numbers [x, y]. The returned point is equal to \([(x - t_x) / k, (y - t_y) / k]\).

Parameters:: location (tuple[float, float]) – Point to inverse
Returns:: Inversed point
Return type:: tuple[float, float]

invert_x(x: float) → float¶

Returns the inverse transformation of the specified x-coordinate, \((x - t_x) / k\).

Parameters:: x (float) – X-coordinate point to inverse
Returns:: Inverse transformation result
Return type:: float

invert_y(y: float) → float¶

Returns the inverse transformation of the specified y-coordinate, \((y - t_y) / k\).

Parameters:: y (float) – y-coordinate point to inverse
Returns:: Inverse transformation result
Return type:: float

__str__() → str¶: Returns "translate({x},{y}) scale({k})".