Class: GeoSubplot

Experimental

A geo subplot laid out (see the module comment).

Constructors

Constructor

new GeoSubplot(input): GeoSubplot;

Experimental

Parameters

Parameter	Type
input	GeoSubplotInput

Returns

GeoSubplot

Properties

Property	Modifier	Type	Default value	Description
chart	readonly	Chart | undefined	undefined	Experimental The chart the subplot was laid out for: what a trace needs its render root for (GPU picking of the regions on a globe, ADR-028) and hover that an asynchronous pick has to run again (chart.refreshHover()). undefined in a hand-built layout context.
gesture	public	boolean	false	Experimental A drag, a pinch or a wheel zoom holds the view: set by the geo component when the gesture starts and cleared when it ends (the pointer is released, the wheel has rested), on every subplot it draws meanwhile. Clearing it is followed by one notify, whether or not the gesture commits anything, so a trace that draws coarser geometry while a gesture turns the map (quick) goes back to its own at that notification and needs no timer.
globe	readonly	boolean	undefined	Experimental The subplot is a 3D globe (projection.type: 'globe3d', ADR-028): it draws in a 3D viewport (see viewport), and its view is the orthographic one.
id	readonly	string	undefined	Experimental
initial	public	| Readonly<Record<string, string | number | false | null>> | undefined	undefined	Experimental The view a reset returns to (a double-click, the 0 key): Plotly's viewInitial, saved by the geo component when the subplot is first drawn and handed to every subplot it draws after. undefined until the component has drawn the subplot.
layers	readonly	BasemapLayers | undefined	undefined	Experimental The basemap of the subplot's resolution and scope that the locations of its traces are matched against (location-data.ts), once it is loaded. undefined until then, and on a subplot without such a trace: the geo component loads the layers it draws on its own.
layout	readonly	FullGeoLayout	undefined	Experimental The subplot's defaulted layout container (fullLayout.geoN).
loading	readonly	Promise<void> | undefined	undefined	Experimental Set while data that the subplot's traces are located with is loading (the basemap, a geojson URL, the country-name table): settles, without rejecting, when the loads have arrived or failed and the layout pass has been asked to run again. Those traces draw nothing until that pass, and hold chart.ready with it (LoadingHold).
quick	public	BasemapLayers | undefined	undefined	Experimental The 110m basemap that stands in for the subplot's own while a gesture turns a map of resolution: 50 (ADR-025), once it is loaded: the geo component loads it, from where config.topojsonURL says, for a map that can turn and that draws a basemap layer or has a trace matched against the basemap (layers), with the extras when the subplot's own basemap has them. undefined otherwise: what turns is then projected from its own geometry.
rect	readonly	Readonly<ViewportRect>	undefined	Experimental The subplot's domain on the plot area, container px (top-left origin).
view	readonly	GeoView | undefined	undefined	Experimental The projection and its current pan, zoom and rotation. undefined while the projection's code is still loading (the projections of d3-geo-projection are a lazy chunk): nothing is drawn until a later pass has it.

Accessors

clipRect

Get Signature

get clipRect(): ViewportRect;

Experimental

Where the subplot draws, in container px (top-left origin): the part of its domain that the range box covers. Fixed for the life of the subplot; a pan moves the map under it.

Returns

ViewportRect

---

globeRadius

Get Signature

get globeRadius(): number;

Experimental

The radius of the globe in px (d3's scale of the orthographic projection): it grows with projection.scale. 0 without a valid view.

Returns

number

---

transform

Get Signature

get transform(): DataTransform;

Experimental

Geometry projected at the view's base state → world units of the subplot's viewport (CSS px from the bottom-left corner of clipRect). Changes with every pan and zoom.

Returns

DataTransform

---

viewportKey

Get Signature

get viewportKey(): string;

Experimental

The key of the globe's 3D viewport at the runtime; the subplot's 2D viewport has the key id. They are two keys because the runtime fixes a key's kind with the first call for it, and because a globe has both.

Returns

string

Methods

basePoint()

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

Experimental

Where a longitude and latitude are in the geometry of the view's base state, the coordinates transform applies to; null when the projection hides the point or the view is not ready. Use it, not GeoView.project, for positions handed to primitives.

Parameters

Parameter	Type
lon	number
lat	number

Returns

[number, number] | null

---

contains()

contains(x, y): boolean;

Experimental

Whether a container point is inside the part of the subplot that draws.

Parameters

Parameter	Type
x	number
y	number

Returns

boolean

---

globeMatrix()

globeMatrix(out): Matrix4;

Experimental

Globe coordinates (the unit sphere of globe-frame.ts) → world units of the globe's viewport, written to out: translate(centre) · scale(radius) · rotation. The rotation is the one d3 applies for the view's projection.rotation, the radius is globeRadius, and the centre is where the 2D code draws the point the rotation faces. So a point of the near hemisphere has the x and y that transform gives its basePoint, and a z above 0; the far hemisphere is below 0. The identity without a valid view.

A pan, a zoom and a rotation each change this matrix and nothing else about the globe.

Parameters

Parameter	Type
out	Matrix4

Returns

Matrix4

---

globeViewport()

globeViewport(ctx, background?):
  | Viewport
  | undefined;

Experimental

The globe's 3D viewport (ADR-028), or undefined on a flat map: an orthographic camera placed by placeCamera, under the subplot's 2D viewport. What is built in globe coordinates goes on its globe (globe-scene.ts: addToGlobe), which this call puts where the view has it.

Parameters

Parameter	Type
ctx	GeoViewportSource
background?	RGBA | null

Returns

| Viewport | undefined

---

notify()

notify(): void;

Experimental

Tell the subscribers that the view changed. A globe's camera follows the view first.

Returns

void

---

onChange()

onChange(listener): () => void;

Experimental

Subscribe to view changes made outside a layout pass (a drag or a wheel step previews through GeoView.set, then calls notify). Compare GeoView.version to tell a move, which only needs transform, from a rotation, which needs projecting again. Returns the unsubscribe function.

Parameters

Parameter	Type
listener	() => void

Returns

() => void

---

placeCamera()

placeCamera(viewport): void;

Experimental

Place the camera of a globe's viewport so that world units are px in the frame of clipRect: x right and y up from its bottom-left corner, as in a 2D viewport, and z towards the viewer, with the globe's centre at z = 0.

The camera looks down −z from the middle of the rect, and half the rect's height is half of what it sees. Its near and far planes follow the globe's radius, which grows with every zoom and soon passes a 3D viewport's default far plane of 1,000: the camera stands 4 radii in front of the centre and sees from 3 radii in front of it to 3 behind (the sphere, and what rises up to a radius above its surface, need 2). viewport calls this in every layout pass and notify after every change of the view between passes. The viewport's own layout() (a resize) keeps the planes: it only sets the frustum's sides.

Parameters

Parameter	Type
viewport	Viewport

Returns

void

---

toBase()

toBase<T>(geometry): T;

Experimental

Takes geometry streamed through GeoView.projection, which is at the view's current state, back to the base state, in place. The projection moves with every pan and zoom while transform carries base geometry, so everything handed to a primitive goes through here; right after a projection the two states are the same and nothing is done.

Type Parameters

Type Parameter
T extends object

Parameters

Parameter	Type
geometry	T

Returns

T

---

toSubplot()

toSubplot(x, y): [number, number];

Experimental

A container point (px, top-left origin) in subplot px, the units of GeoView.project and GeoView.invert.

Parameters

Parameter	Type
x	number
y	number

Returns

[number, number]

---

viewport()

viewport(ctx, background?):
  | Viewport
  | undefined;

Experimental

The subplot's 2D viewport, from the runtime: world units are px from the bottom-left corner of clipRect, and everything positioned in subplot px is drawn here (base layers of a flat map; markers, text and the frame on any map). The one place that asks for it, used by the geo component and by the subplot's traces. undefined when ctx hands out no subplot viewports (a hand-built context).

On a globe this viewport lies over the globe's own (globeViewport), which is asked for first so that it is drawn first, and which then has the background.

The runtime sets a viewport's background on every call. background is therefore remembered per viewport: leave it out to keep what the viewport has, as a trace does, which does not decide the subplot's background.

Parameters

Parameter	Type
ctx	GeoViewportSource
background?	RGBA | null

Returns

| Viewport | undefined