Class: GeoView

One geo subplot's projection and view. Build it with createGeoView.

To draw: stream geometry through projection (or project points with project), remember version, and give the primitives transform on every frame. Reproject when version has changed. When a zoom has settled, call rebase and reproject.

Properties

Property	Modifier	Type	Description
bounds	readonly	GeoBounds	The pixel bounds of the range box at the fitted view (Plotly's this.bounds): the clip rectangle of the map and its background. It does not move with a pan or zoom.
clipAngle	readonly	number | null	The angle from the rotation's centre past which a point is hidden, in degrees, or null when the projection shows the whole sphere.
fitScale	readonly	number	d3's scale when projection.scale is 1 (Plotly's fitScale).
initialState	readonly	GeoViewState	The state the layout (and the fit) describe, before any interaction.
layout	readonly	FullGeoLayout	The container this view was built from.
midPoint	readonly	Pair	The middle of bounds (Plotly's midPt), where center is read back from.
mode	readonly	GeoInteractionMode	Which of Plotly's interactions the map has.
projection	readonly	GeoProjection	The d3 projection at the current state, for streaming geometry (projection.stream) and for d3's own helpers. Its output is d3 px: x from the left edge of the subplot's rect, y down from its top edge, so a sink writes size.height - y to get subplot px. It has no clipExtent; clip to bounds. Geometry streamed here is at the current state, while transform applies to geometry of the base state: call rebase before projecting unless version has just changed. Do not call its setters; change the view with set.
ranges	readonly	object	The ranges of the range box: the axis ranges, or what fitbounds made of them.
ranges.lat	readonly	Pair	-
ranges.lon	readonly	Pair	-
scaleExtent	readonly	Pair	The least and greatest projection.scale an interaction may reach (minscale, maxscale).
size	readonly	GeoSize	The subplot's rect; projection draws into [0, width] × [0, height], y down.
type	readonly	string	projection.type.
valid	readonly	boolean	false when the fit failed (an empty rect or ranges d3 cannot bound): nothing can be drawn.

Accessors

state

Get Signature

get state(): GeoViewState;

The current rotation, scale and translate point.

Returns

GeoViewState

---

transform

Get Signature

get transform(): Readonly<DataTransform>;

Carries geometry projected at the base state (subplot px) to where the current pan and zoom draw it: world = data * scale + offset. The identity right after a projection.

Returns

Readonly<DataTransform>

---

version

Get Signature

get version(): number;

Names the projection that geometry was made with. It changes when geometry projected earlier no longer fits this view: after a rotation and after rebase. It is unique across views, so a view of another type, size or parallels has another version too.

Returns

number

Methods

invert()

invert(x, y): [number, number] | null;

The longitude and latitude drawn at a subplot px in the current view; null when the pixel is off the map. d3's inverses answer for any pixel (off an orthographic disc they give the nearest point of its edge), so a pixel counts as on the map when its longitude and latitude are drawn within INSIDE_TOLERANCE_PX of it (Plotly's outside test) and the projection does not hide them.

Parameters

Parameter	Type
x	number
y	number

Returns

[number, number] | null

---

invertAt()

invertAt(
   state,
   x,
   y
): [number, number] | null;

d3's inverse at another state of this view, without the on-the-map test of invert; null when it is missing or not finite.

Parameters

Parameter	Type
state	GeoViewState
x	number
y	number

Returns

[number, number] | null

---

isLonLatOverEdges()

isLonLatOverEdges(lon, lat): boolean;

Plotly's isLonLatOverEdges: whether the projection hides a point, either because it has no pixel for it (outside the three parts of Albers USA) or because it lies past the clip angle (the far side of an orthographic globe).

Parameters

Parameter	Type
lon	number
lat	number

Returns

boolean

---

project()

project(lon, lat): [number, number] | null;

Where a longitude and latitude are drawn in the current view, in subplot px; null when the projection hides the point (isLonLatOverEdges) or has no finite answer. Points outside bounds are returned: the subplot's scissor hides those.

Parameters

Parameter	Type
lon	number
lat	number

Returns

[number, number] | null

---

projectAt()

projectAt(
   state,
   lon,
   lat
): [number, number] | null;

d3's answer for a longitude and latitude at another state of this view, in subplot px, without the clip test of project. For interaction maths, which asks where things would be.

Parameters

Parameter	Type
state	GeoViewState
lon	number
lat	number

Returns

[number, number] | null

---

rebase()

rebase(): boolean;

Makes the current state the base: transform becomes the identity and version changes, so the caller reprojects. Call it when a zoom has settled (curves resampled at the old scale drift). Returns whether anything changed; a view already at its base is left alone.

Returns

boolean

---

set()

set(patch): this;

Changes the view for an interactive preview. scale and translate change the transform only; a rotation makes the new state the base and changes version. A projection that cannot rotate (Albers USA) ignores rotation.

Parameters

Parameter	Type
patch	GeoViewPatch

Returns

this

---

toLayout()

toLayout(state?): GeoLayoutView;

The view as the layout values Plotly writes when an interaction ends: the rotation, the longitude and latitude in the middle of the bounds as center, and projection.scale. center is d3's inverse as it is, which is what Plotly writes.

Parameters

Parameter	Type
state	GeoViewState

Returns

GeoLayoutView