Creates a new contour trace.
The MAIDR layer carrying one curve per level
Protected ReadonlyobserversProtectedisProtectedisTrue while AbstractTrace.getStateAt computes state at a temporarily moved cursor. Enforces (structurally, not just by documentation) that state getters never notify observers.
Protected ReadonlyidProtected ReadonlytypeProtected ReadonlytitleProtected ReadonlynameWhat this layer is, when the producer named it. See MaidrLayer.name.
Protected ReadonlylayerProtected ReadonlysupportsAbstract property that subclasses must implement to indicate extrema support
Protected ReadonlyrotorProtected ReadonlymovableProtected ReadonlypointsProtected ReadonlylineProtected ReadonlyhighlightOne entry per point, or -- where a series is drawn as several elements
with no way to tell which is which -- the whole set behind every point of
it, outlined together. ContourTrace is the case: a level with
islands has one <path> per island and no dependable order among them
(xability/maidr#1142).
Protected ReadonlylineThe rendered <path>, <polyline> or <polygon> of each series, when the highlight
markers were synthesised from one.
mapViaPathParsing builds a circle per data point and throws the element it read them out of away, so the trace's own highlight list holds the vertices of the line and nothing of the line itself. Anything drawing the trace from those markers therefore draws a scatter of dots where the chart drew a continuous line -- which on a tactile display is not a cosmetic difference: the segments between vertices are most of the geometry, and without them a zoomed-in view whose window falls between two points has nothing in it at all.
Empty when the markers are the chart's own dot elements (mapViaDomElements), where the connecting line is a separate element this trace never resolved and so cannot offer.
ProtectedhighlightProtected ReadonlyminEach series' own lowest and highest measured value, which [ and ]
jump to within the series the cursor is on.
Protected ReadonlymaxProtectedcategoriesWhether this trace's grid lists its categories as columns while the chart draws them one above another: a horizontal bar, dot, lollipop, funnel, dumbbell or forest chart. Its arrow keys are then turned to follow the drawing (keyDirection), as a horizontal box plot's already were: Up and Down move between the categories, and Left and Right along one, between the series, ends or sections drawn across it.
False here; true on the traces of that shape drawn on their side
ProtectedxThe x axis's name, falling back to a generic one the layer authored none.
A getter rather than a field set in the constructor: the fallback is a translated word, and a trace outlives a language change — a name resolved once at construction would keep the language the chart was built in.
ProtectedyThe y axis's name, or a generic one. See xAxis.
ProtectedzThe z axis's name, or a generic one. See xAxis.
ProtectedisWhether the cursor has no point to report.
Read from dimension rather than from any one trace's data,
because that is the one shape every trace already answers in. It is also
evaluated at the cursor — LineTrace returns the current series'
length as cols — so this covers a ragged layer, where one series has
points and another has none, and not only a layer that is empty
throughout.
True when there is nothing at (row, col) to describe
ProtectedhighlightProtectedautoplayProtectedhasHow this layer names itself in the description dialog's layer tabs.
The producer's name when there is one, and the chart-type label
otherwise — the same fallback order TextService.layerIdentity uses for
the spoken layer-switch announcement, so a tab and the announcement single
out the same layer by the same name. The two differ only in register: the
announcement says "point plot" where the dialog says "Scatter Plot",
because that written form is what the dialog's own Chart Type line has
always shown and a tab sitting above it should agree with it.
A plain-language introduction to this layer's chart type, for the description dialog. See chartGuide.
A layer that names its own chart type never gets the trace type's: that guide explains the type the chart is read as, which is not what the chart is, and a gantt's tasks, dates and project plans said of a packet's bit fields are false. It gets the guide to the diagram it names (MaidrLayer.diagramType), or the one it gives to its own chart (MaidrLayer.typeGuide), or none.
Which way this chart is drawn, or undefined for a type that has no orientation to speak of.
Entering the chart already announces it -- "This is a maidr plot of type: horizontal bar" -- but the description dialog said only "Chart Type: Bar Chart", and for the box, violin and boxen families the orientation also silently reverses the order of the rows in the table underneath, because their constructors reverse the groups when the chart is horizontal. A reader comparing the table with what they walked had no way to know why the two disagreed.
Exposed here, and read once by the description service, rather than pushed
as a stat by each of the thirty-odd traces that has one. Named apart from
the bar and distribution families' own orientation fields, which hold the
declared* value and default it to vertical for every type -- including the
ones that have no orientation at all.
horizontal or vertical, or undefined when the type has no
orientation to report.
How far the layer's measured values spread: its largest less its
smallest, or 0 with fewer than two. The scale at which [, ] and the
Go To dialog read two values as one extreme
(MathUtil.nearlyEqualInRange).
Read from values, the numbers the layer is sounded and brailled from; a trace whose extrema rank something else says so by overriding it.
The span, never negative
The trace's chart type. Lightweight alternative to reading
state.traceType, which eagerly computes the full audio/braille/text/
highlight state just to expose this one string.
The state the entry instruction is built from names a contour plot and counts its levels: inherited, it said "multiline with 4 groups", which is the line chart this trace is built on, not the chart the reader is on.
The line's state, as a contour plot
ProtectedgroupWhat this chart calls one of its series, when the layer names no z axis.
Overridable for the reason LineTrace.seriesLabels is: a subclass navigates the same grid but draws something else, and this label is announced literally beside the series' own name. A chart that named its own noun everywhere else and then said "Group is Honda Civic" -- or "Group is Ash" -- would use two words for one referent in a single sentence.
The fallback label
ProtectedseriesThe vocabulary the description dialog is rendered with.
Inherited, a contour's description opens "Number of lines: 3, Points per
line: 40, Line names: Line 1, Line 2, Line 3" and its data table has a
Line column of Line 1 -- the reading this class exists to replace,
printed in the part of the description a reader consults most.
The four labels the description uses
ProtectedtextGets the description state for the line trace.
The description state containing chart metadata and data table
ProtectedvaluesProtectedvalueThe range every series is pitched and brailled against: the lowest and the highest measured value of the whole layer.
One range for the layer, as a bar layer has one, because the series of a line chart are drawn against one value axis. Pitched each against its own range, every line's own lowest point played the bottom note and its own highest the top one, so a smaller value on one line could sound higher than a larger value on another, and unequal values on two lines played the same note.
The tone at the cursor, the chord at a point several series share and the braille all read it, so a subclass heard on another register overrides this one getter and all three follow. A bump chart, whose register runs the other way round, keeps its braille the right way up with an override of its own.
The lowest and highest value of the register
ProtectedaudioProtectedvaluesWhether a value is where the series is drawn on the value axis, rather than a magnitude measured out from a baseline.
True of a line: a 0 between negative and positive values is a place on the axis, and is pitched there. A filled mark -- an area's band, a polar area's wedge -- is a magnitude, as a bar is, and its 0 is no band and no wedge, which the null tone marks; those traces answer false.
True when the layer's values are positions
ProtectedoutThe boundary tone sounds where the point the reader stopped at sounds.
The base pans it by column index, which is this family's own sweep, and so was right only where panningFor is not overridden. A radar's point pans by its spoke's angle and its boundary chimed by the spoke's index: the 3 o'clock spoke, heard on the right, chimed left of centre, and the 9 o'clock spoke hard right. A ROC or precision-recall curve's point pans by its rate and a parallel coordinates' by its axis, and their boundaries chimed by index as well.
The empty trace state, panned to the cursor's point
ProtectedbrailleProtecteddimensionProtectedseriesWhether two series meet where their values are equal.
True of lines, which are drawn at their own values: two lines with one value at an x share that point of the drawing, and two whose values pass each other cross. A subclass whose series are drawn somewhere other than at their values -- a stacked area's band sits on the bands below it -- answers false, and then no point is announced or sounded as an intersection, and neither the extrema list nor the rotor offers one.
True when series meet where their values do
ProtectedlaterWhether series stacked level with each other put the later one above.
True of a line, whose column reads a tie as the last of the joint highest and the first of the joint lowest. A subclass that stacks a tie the other way round answers false. Read while the graph is built in the constructor, so an override returns a constant.
True when the later of two level series is the higher one
Runs action with this element's observers muted.
A cursor move normally is the announcement -- moveToIndex notifies, and
everything downstream of it speaks, brailles and highlights. That is wrong
for a move the reader did not make and is not waiting to hear: the
description dialog's layer tabs relocate the reader in the chart while the
modal is open, and the trace's announcement would land in the same live
region the dialog is using, so one of the two is dropped. The caller
announces afterwards, once, when the reader is back on the chart.
Nesting is safe and the flag is restored on every path, including a throw, because a flag left raised would silence the chart for good.
The moves to make in silence
ProtectedgetGets safe row and column indices to prevent accessing undefined values
Object with safe row and column indices
Registers an observer to receive state updates.
The observer to add
Removes an observer from receiving state updates.
The observer to remove
Notifies all registered observers with the current state.
Notifies observers that an out-of-bounds condition occurred.
Utility function to compare point values for rotor functionality
boolean value
ProtectedcompareRotor compare search along one row of numeric values.
Steps from the current column in the given direction and moves to the first value that satisfies the comparison; reports the rotor boundary when nothing further qualifies. For the traces whose values are a plain numeric grid indexed [row][col]; a trace with a richer layout (the bar's orientation-normalised rows, the candlestick's segments) keeps its own.
The values of the row being searched
Which way to search
Whether a lower or a higher value is sought
True when a matching value was found and moved to
Whether the rotor offers its lower and higher value modes on this trace.
Exactly when the trace overrides moveToNextCompareValue. The base search is a no-op that reports a boundary, so offering the modes without one told a reader "No lower value found" with a lower value beside them, or said nothing at all; tying the offer to the search keeps the two from drifting apart again. A subclass can still override this to withhold the modes (scatter, whose arrows walk points rather than values), and a trace that compares only through the rotor's arrow methods must override it to offer them.
Returns the display name for the default data navigation mode. Override to provide a trace-specific name (e.g., "ROW AND COLUMN NAVIGATION" for scatter).
Returns the rotor's compare-mode labels and boundary-message nouns. Override to rename the two compare units for a trace-specific semantic (e.g., the candlestick delta layer uses "above line" / "below line").
The rotor, Left: on a chart drawn on its side, the plain move along the category, as a horizontal box plot's rotor moves along its box. The search runs along the categories, which Up and Down walk there.
Optionalmode: "lower" | "higher"Whether a lower or a higher value is sought
Whether the cursor moved. False at the end of the category -- on a chart of one series, always -- so the rotor says there is nothing further that way; it reported true, and the rotor said nothing.
The rotor, Right. See moveLeftRotor.
Optionalmode: "lower" | "higher"Whether a lower or a higher value is sought
Whether the cursor moved, false at the end of the category
ProtectedkeyThe direction to move the grid for a key, which is the key's own except on a trace whose categories run down the page. There the grid's columns are drawn one above another and its rows across them, so Up and Down step the columns, toward the category drawn above or below, and Right and Left step the rows. On a horizontal bar chart Right and Left moved down and up the page between the bars, and Up and Down said there was no more data: the other way round from a horizontal box plot or violin.
The key's direction
The direction to move the grid in
ProtectedfirstWhether the first category is drawn above the last.
Producers list a horizontal chart's categories both ways: matplotlib, ggplot2, base R and Plotly draw the first at the bottom, and Highcharts, ApexCharts, Vega-Lite, seaborn and most hand-drawn charts at the top. So it is measured, as a Gantt chart measures its lanes, from the marks the highlight holds: in the first row that has two, the first category's mark is above the last one's, or below it. Measured on every vertical key, an autoplay step included, rather than once. That is two boxes a key, however many categories the chart has: the two marks are found from the ends of the row, and the read forces at most the layout the highlight's move would cause before the next paint. An answer kept from the first key was kept from a chart not yet laid out, or one since re-rendered the other way round, and a cache would have to be cleared on every redraw and resize to avoid that.
Where nothing can be measured now, the last measurement holds, so a chart hidden for a moment does not turn the keys round under the reader. Where nothing has ever been measured -- a chart drawn to a canvas, one with no highlight, one not laid out yet, or one category -- the layer's MaidrLayer.firstCategory says where the first is drawn. Without it, the first is taken to be at the bottom, as row 0 of a grid is, and Up moves to the next.
True when the first category is drawn at the top
ProtectedauthoredThe format the layer's author declared for an axis, or null when they declared none.
For a number the description states rather than tabulates. The table reads each column through the axis's declared format, and so does every announcement, but a stat printed the raw number: a margin drawn as a percentage was "Min value: 0.12" over a table and a cursor saying 12%. Null rather than the default format when nothing was declared, so a chart nobody formatted reads as it did, which is the rule the table follows.
Taken from FormatUtil.axisFormat, as the announcements and the table take theirs, so a histogram's bin edges read with the same decimals in all three.
The axis whose format to read
The format, or null when the layer declared none
Get all highlight SVG elements for this trace Used by HighlightService for high contrast mode
Array of all SVG elements, or empty array if none
ProtectedoriginalThe chart's own element a marker this trace drew stands for, where the trace marks a point with a dot of its own rather than with a copy of the mark. None by default.
A marker in this trace's highlight values
The element the marker stands for, or null
Get all original (visible) SVG elements for this trace. These are the actual rendered elements, not the hidden clones used for highlighting. Used by HighlightService for high contrast mode color changes.
Array of all original SVG elements, or empty array if none
ProtectedgetComputes the trace state at an arbitrary position without moving the user's cursor or notifying observers. Used by monitor mode to sonify and announce a newly appended point while the user stays put.
The state getters read this.row/this.col internally, so the cursor
is moved temporarily and always restored in a finally block — this
method is the single owner of that pattern.
Re-entrancy hazard: this is only safe because the entire call chain is synchronous (no await points), so timers (e.g. autoplay ticks) cannot interleave before the finally-restore, and state getters never notify observers. If a getter ever becomes async or triggers notifications, callers could observe the temporary cursor.
The row of the position to compute state for
The column of the position to compute state for
The trace state at the requested position
Resets the trace to initial entry state
ProtectedgetReturns a human-readable label for this trace's chart type (e.g., 'Bar Chart', 'Scatter Plot') for display in the description modal. Falls back to the raw layer type if no mapping is registered.
ProtectedspokenWhat the entry instruction calls this chart: the name the layer gives its own chart type (MaidrLayer.diagramType or MaidrLayer.typeLabel), or the trace's word.
A trace that names itself -- a line "single line" or "multiline", a radar "polar area" -- passes its word through here, so a layer that names its chart type is called by that name whichever trace reads it, and the instruction a reader hears once in the chart says what the one built from the layer before it said.
The trace's word for its type
The word the instruction uses
ProtectedgetBuilds the axes object for the description state, carrying only the axes the layer actually authored a label for. Subclasses should call this instead of constructing the axes object inline so charts without a real z dimension don't surface the placeholder default.
Every axis is gated, not just z. xAxis and yAxis fall back to the
literal 'X' and 'Y' when the JSON authors no label -- legal, and
common in adapter-generated specs -- and the dialog rendered that as
"X: X", a line that says nothing twice. The figure-level branch of the
description already showed only authored labels
(DescriptionService.getFigureAxes), so gating here is what makes
the two levels of the same dialog follow one rule.
Blankness is tested with trim(), the same rule named applies
when it decides whether to substitute the fallback in the first place. A
whitespace-only z label is truthy but blank, so the untrimmed guard used
to pass it through and then print the 'Level' placeholder the guard
existed to keep out.
Whether the cursor stands on an extremum target, for a trace whose cursor its row and column do not hold: a scatter plot in point navigation keeps a point's index instead. Null leaves the answer to the row and column, which is how every other trace's cursor is read.
A target from getExtremaTargets
True or false where the trace keeps its cursor elsewhere, and otherwise null
ProtectedfinalizeCommon post-navigation cleanup that should be called by subclasses after they update their internal state
Returns true if this trace supports point-by-point navigation mode. Opt-in per trace type: override to return true for traces that expose individual data points navigable in reading order (left/right) and column-major order (up/down). Currently only ScatterTrace.
Notifies the trace that the rotor is entering or leaving INTERSECTION_MODE. Default is a no-op; line-style traces don't need to track mode state because their state output is unchanged by the rotor mode. Traces whose audio/text output differs in intersection mode (e.g. ScatterTrace, which normally plays the whole x-column as a chord and must instead focus a single point) override this to flip an internal flag.
True when entering intersection mode, false when leaving.
Trace-specific rotor filter units appended to the rotor cycle after the built-in data/compare/grid/intersection modes. Each unit restricts navigation to points matching a predicate (e.g. only bullish candles). Default: none. Override to opt in (e.g. Candlestick exposes bullish/bearish/neutral units). The returned list is treated as read-only by the rotor service.
Notifies the trace which of its getRotorFilterUnits the rotor is on, or null when it is on none of them. Default is a no-op: a unit usually changes only where Left and Right go, which moveToRotorFilter answers. A trace whose unit also changes what Control with them should reach -- a tree's Level, where Left and Right walk the whole level -- overrides this, because the jump is not routed through the rotor.
The RotorFilterUnit.key of the active unit, or null
Moves within an active rotor filter unit along the filtered axis.
Called by RotorNavigationService when the current rotor mode is
one of this trace's getRotorFilterUnits. Filter units navigate a
single axis, so only left/right are dispatched here — the service
announces up/down as unavailable without calling the model (matching
intersection mode). Implementations should move to the nearest point
matching the unit identified by key and notify observers, returning
true; when no such point exists they should call notifyRotorBounds
and return false.
Default is a no-op that reports bounds, so a trace advertising a filter unit but forgetting to implement movement fails safe (announces "no point found") rather than moving unexpectedly.
The RotorFilterUnit.key of the active unit
The direction to search
True if the cursor moved, false otherwise
Every object the o list offers on this chart, or null where there is
none to offer.
Null for every chart walked along x and y axes: the arrows already reach each point in order there, and a list of them would repeat the axis. A chart whose objects have no such order -- the nodes of a network, the tiles of a treemap -- overrides this and builds the list from its own structure, with the sorts and filters that make sense for it.
List only, as the rotor units are, with no flag beside it: a flag that said yes over an empty list would open a dialog with nothing to choose. Labels are built on each call, because the trace outlives a change of language; anything expensive to compute is kept by the trace that computes it.
The list, or null
Moves to the object the list knows by this key, announcing it through the usual observer chain.
Looks the key up in a list built now rather than trusting a cell the dialog was handed when it opened, so a chart whose data changed under the dialog moves the reader to the object they chose or nowhere at all.
The key the object list gave the object
True when the cursor moved, false when no object has the key or its cell cannot be reached
Checks if this plot supports extrema navigation.
True if extrema navigation is supported
Why this layer has no extremum for [, ] and G to go to, where that
is by design: what the layer lacks, as a phrase in the reader's language,
which the refusal says after it says there is nothing to go to. Null
where the layer has extrema, or has none only because of its data.
Asked with the extreme a bracket key wants, a layer that has one of the
two by design and not the other can say why for the one it lacks, as a
ROC curve does for [. G, which lists both, asks without one.
Optional_extreme: "min" | "max"The extreme [ ('min') or ] ('max') asked for,
or nothing for the layer as a whole
The reason, or null
Base implementation for getting current X value Subclasses can override if they have different data structures
Whether a mark of this trace sits at exactly this X, as moveToXValue finds one before it falls back to the nearest.
A layer switch asks this to choose between the two X values a position
can offer (see Trace.getAlternateXValue). Reads the x of each point;
a trace that keeps its X some other way answers false unless it says
otherwise, and the switch then carries what it always carried.
The X a layer switch would carry
True when some point's x is exactly xValue
How this layer's x axis writes an x: through the format the layer declares for it, or null where it declares none.
A layer switch carries a number this way to a layer that holds the same
place as text (see Subplot.carriedXValue).
An x of this layer's
Its reading, or null
The x of this layer's that its axis writes as reading: the first in
the order the points are held, or null where the layer declares no x
format or none of its x reads that way.
A layer switch carries text this way to a layer that holds the same
place as a number its axis formats (see Subplot.carriedXValue).
The text another layer holds the place as
The x, or null
Gets the unique identifier for this trace.
The trace ID
Moves the active point to the pointer location and returns directional guidance toward the nearest data geometry in a single call.
Combining both operations avoids running findNearestPoint twice per
pointermove event — important on dense plots where the scan is the
hot path.
Screen-space x position of the pointer/finger
Screen-space y position of the pointer/finger
Guidance state relative to nearest point, or null when unavailable
ProtectedmoveMoves the trace to the nearest point when the pointer is within its bounds and the trace is not already focused on that point.
onCurve is intentionally non-optional: the caller has already paid
the cost of isPointInBounds to assemble guidance state, and
forcing subclasses to accept the value makes the contract explicit so a
future override cannot silently recompute (or worse, ignore) it.
Subclasses override this to customise hover-driven navigation:
Checks if the specified coordinates are within bounds of the element.
The x-coordinate
The y-coordinate
Object containing the SVG element and its position
True if the point is in bounds, false otherwise
ProtectedfindWhere Up and Down land: the nearest point of the next level up or down.
Inherited, Up and Down looked for another curve with a point at the reader's exact x and a larger or smaller y, which is how a line chart's series line up. Contour curves share no x values: each is traced where the field crosses its own level. So a reader could leave a level only from the one or two points where two curves happened to share an x, and heard "No more data" everywhere else. On a contour plot up is the next level up, and the place on it is the one nearest the reader's.
A curve that declares no level has no next level, and keeps the line chart's reading.
UPWARD for the next level up, DOWNWARD for the next down
The row and column to move to, or null at the top or bottom level
Control+Up and Control+Down go to the highest and the lowest level, at the point of it nearest the reader's.
Inherited, they went to the top or bottom of the reader's column of a line chart, matched by point index -- an index that is a different place on every curve -- so they landed on an arbitrary curve rather than the highest or lowest level, and the next Up or Down still moved.
On the highest level already, Control+Up stays and says the point again, as a jump to the end of a grid does on every other chart.
The direction to jump in
Whether the reader moved
ProtectedmapWhere a level's highlight lands.
A contour is the one line-shaped trace whose series is not reliably one
drawn element. Plotly writes one <path> per curve under one
g.contourlevel per level, and only the level is dependably
addressable. Measured for xability/py-maidr#643 across 33 fields and 207
levels -- random sums of gaussians, a saddle, a monkey saddle, ripples, a
staircase, noise -- against what contourpy traces from the same grid:
levels where the counts disagreed 0 / 207
levels where the order within one did 18 / 207
Five of the eighteen were ordinary two-peaked gaussian fields, so
g.contourlevel:nth-of-type(k) is dependable and ... path:nth-of-type(j)
is not. Inherited, that left a producer two options: a per-curve selector
that resolves to a real element and the wrong one, or no selector at all
and no highlight (xability/maidr#1142).
So a selector resolving to several elements is read as a level rather
than a curve, and every point of that series outlines all of them. That is
the reading matplotlib's contour has always given -- it draws one <path>
per level, so naming the level names an element -- and a reader on one
island of the 0.5 contour sees the 0.5 contour outlined.
Decided per level rather than per layer, because a field usually has islands at some levels and not others, and a reader on a single-curve level keeps the per-point highlight that walks with them.
The selector resolves to the paths rather than naming the g.contourlevel
itself because, when this was written, Svg.createHighlightElement set
stroke on the group's clone alone, and stroke is inherited only by a
child that declares none -- plotly stamps one on every contour path, so
the clone came out colourless. A group is outlined through its shapes
now, but producers emit the paths, and this reading is what they emit
against.
Optionalselectors: string[]One selector per level, as the layer declared them
The elements to outline, point by point
ProtectedreconcileWhere each point of a curve is marked when the path drawn for it does not have a vertex per point.
Inherited, the points were spread by x between the path's first and last vertex and read off the path there, which is how a line chart gets back the points a renderer dropped from a straight run. A contour curve is not a function of x. Plotly draws its curves from its own pass over the grid, so they rarely have a vertex per point, and on the Plotly contour example the 0.2 level starts and ends on the plot's right edge: its first and last vertex share an x, and all 122 of its points were marked at one spot. matplotlib drops vertices from a path of 128 or more when it draws it, and the same reading put a ring's mark on its first vertex, or across the ring from the point read.
The points and the path are one curve, so the box the points span is the box the path spans: the smallest and largest x of the one are the left and right edges of the other, and the same for y. Each point is taken through that box and marked at the nearest place on the drawn path, looked for near where the point before it was marked: consecutive points are neighbours on the curve, and a search of the whole path could take a point onto another stretch of it that passes close by. The path is read subpath by subpath, so no point is marked on a line between two of them that the path never draws.
The box does not say which way an axis runs. The usual way, x to the right and y up, is kept whenever it lays the points on the path to within ORIENTATION_TOLERANCE of its size. On a ring that is symmetric about an axis its mirror image fits as well, and can fit a fraction of a pixel better where the renderer moved a vertex; taking the closest fit then marked every point across the ring from where it is. Only when the usual way leaves the points off the path is the way that lays them closest taken instead: a chart that reverses an axis.
A path with a vertex per point is left as it is, and so is the line chart's reading where the boxes cannot be matched: a curve or a path with no extent along an axis the other spans.
Vertices parsed from the path, mutated in place
Index of the curve
Optionalruns: readonly ShapeOutline[]The same vertices, subpath by subpath
ProtectedgroupWhat a curve is called wherever the description names one.
The level, because that is what the curve is. Line 2 is an index into
the order the producer happened to emit the curves in, and a reader given
it in a column headed Level would reasonably take it for one.
Rounded as the announcement rounds it. A producer computing its levels
hands over floats -- matplotlib's 0.15 step reaches 0.45 as
0.45000000000000007 -- and in full they were listed beside a Level range and a Level step the description had rounded, while every point
of the curve announced Level is 0.45.
Which curve
Its level, or the best name available for a curve declaring none
ProtectedlistedWhether a series is listed from its right end to its left, and so is read turned round.
False for a line: its points are walked in the order they are listed, which on a category axis is the order they are drawn in. A layer type whose producers may list a series either way round answers for it.
Called from the constructor, before a subclass's own fields are set, so an override reads only the series it is given.
The series' points, as listed
True when the series is to be read in the reverse of its listed order
ProtectedauthoredName a line carries in the spec, or undefined when the data authors
none. Consumers that have nothing meaningful to say without a real name
(e.g. the position announcement) can then stay silent about groups.
Protected for the same reason LineTrace.groupNameAt is: a subclass
that names its series from its own data -- a contour from its level --
still has to answer for a series the layer named and nothing else did, and
calling groupNameAt for that would recurse.
Gets the line series with human-readable labels. Used by the candlestick delta feature to list reference-line candidates (e.g., moving averages).
One entry per series with its label and points
Cleans up trace resources including values and highlighted SVG elements.
Only removes elements MAIDR created (hidden clones, synthetic markers); traces that highlight the chart's original live elements in place (e.g. heatmap cells, line dots) merely drop their references so the visible chart geometry survives focusout and live-data rebuilds.
ProtectedpanningWhere a cell sits in the stereo field.
Split out because three places need it and they must agree: the tone for the cursor's own point, the tones of every series a chord sounds at an intersection, and the boundary tone of a move refused there. A subclass that hears its columns somewhere other than a straight left-to-right sweep -- a radar's spokes go out and back around a circle -- overrides this one method and all three follow, rather than one of them keeping the line's sweep and contradicting the others.
The series index
The column index
The panning for that cell
ProtectedenterEstablishes the cursor on the first move into the trace.
MovableGraph.handleInitialEntry tries (0, 0) and otherwise parks the
cursor at (-1, -1). A ragged layer whose first series is empty -- a
hue level with no data in the range, emitted before the ones that have
some -- has points to land on all the same, so the cursor is moved to the
first series that has any rather than left off the data.
Moves the way the key points on the drawing. See categoriesRunDown.
The key's direction
Whether the cursor moved
Movability by the same rule, so check-then-move (autoplay's idiom) agrees with the move it checks.
A direction, or a cell
Whether the move is possible
ProtectedliesWhether one series lies below another in a column: its value is lower, or the two are level and the series order stacks it below (LineTrace.laterSeriesAbove).
The one order Up and Down walk and Control + Up and Down jump to the ends of. Level series are stacked rather than refused: refusing a tie made a point two series share a dead end for Up and Down, although another series sits at that very cell.
Values the same but for float noise are level
(MathUtil.nearlyEqualRelative). Values computed two ways carry that
noise, and compared exactly a tie the chart draws as one point became an
order of its own: 0.1 + 0.2 stood above 0.3. The margin is a billionth
of the values' own size, so small values keep their order however small
they are: a series at 1e-12 lies below one at 5e-11, and a KDE's tail of
9.4e-28 above a curve that is 0 there.
Being level is not transitive: a can be level with b, and b with c, while a lies below c. Values that close read the same, so at worst the order the series are scanned in decides which of them is the top or the nearest.
One series, by row and its value in the column
Its row
Its value
The other
Its row
Its value
True when a is below b
ProtectednearestOf the other series in the cursor's column, the nearest above or below the cursor in the order LineTrace.liesBelow reads.
The values are compared with each other, never through their distance to the cursor: a difference rounds to the nearest double, and two candidates whose distances rounded alike were taken as tied and one of them was passed over. At -6.57 on the Altair KDE example the distances from 0.012 to 9.4e-28 and to 0 are one double, so Down from 0.012 took the later curve, at 0, as the nearer and never reached the one at 9.4e-28. A candidate level with the cursor is placed at the cursor's own value, so the series order alone decides between the series of a tie and the tie is walked one series at a time.
UPWARD for the nearest series above, DOWNWARD for the nearest below
The value at the cursor
The other series, each with its value in this column
The nearest candidate that way, or null when there is none
ProtectedfindFinds the column index for a given X value in a specific line Uses strict equality (===) for X value matching. Protected so a subclass that chooses the series differently (a radar, by series order) still finds that series' column the same way.
The line index
The X value to find
The column index, or -1 if not found
The elements whose geometry is the line itself, for renderers that need the drawn shape rather than the points on it.
See lineElements for why the highlight markers are not that shape. Empty when this trace's markers are the chart's own, in which case the caller should fall back to them.
ProtectedofferRecords the stroke the chart drew through a series' own markers, when there is one to find.
A chart that renders a dot per point usually draws the line through them as well, in the same group -- a radar's polygon, a Recharts line's path -- and that line is the series' shape where the dots are only its vertices. The selector named the dots, so the line is the one sibling of theirs that draws a stroke. It is offered as geometry so a renderer that wants the shape has it; nothing else about the trace reads it.
Nothing is offered when the answer is unclear: markers spread over several groups, a group with two strokes in it (a line and its area), a stroke that does not reach the markers. A wrong shape on the display is worse than none.
The chart's own elements for one series
ProtectedinterpolateOne vertex per data point, placed along an edge by x.
Each point's x is mapped linearly from the series' x range onto
[xMin, xMax], and its y is read off the edge there: at a vertex within
snapWithin of that x, the vertex itself; otherwise interpolated along
the segment that spans it. This is how a simplified path gets its dropped
points back, and how a band drawn with more vertices than it has samples
finds the samples among them (see AreaTrace).
Vertices in drawing order
Index of the series the edge belongs to
The SVG x the series' first x maps onto
The SVG x the series' last x maps onto
How close in x a vertex has to be to a point to stand in for it exactly; 0 always interpolates
Optionalonly: readonly number[]The indices of the points to place, in the order to place
them; every point when omitted. The first and last of them map onto
xMin and xMax.
One vertex per data point placed, in the order placed
ProtectedmapGet extrema targets for the current line plot Returns min, max values, and intersection points within the current group
Array of extrema targets for navigation
ProtectedcrossingWhere a crossing strictly between two categories is, as the Go To dialog says it: the two categories and the value at the crossing.
The category before the crossing
The category after it
The value at the crossing, formatted
The coordinates, in the reader's language
Navigate to a specific extrema target
The extrema target to navigate to
ProtectedupdateUpdate the visual position of the current point This method should be called when navigation changes
Move the line plot to the position that matches the given X value
The X value to move to
true if the position was found and set, false otherwise
The rotor's LOWER and HIGHER VALUE search. The base is a no-op that reports the boundary: a trace that can compare overrides it, and supportsCompareMode offers the two modes exactly where it does.
The rotor's lower and higher value search, Up: on a chart drawn on its side, along the categories toward the one drawn above, as Up moves. Elsewhere the rotor reads Up as Right.
Optional_mode: "lower" | "higher"Whether the cursor moved
The rotor's search, Down: toward the category drawn below. See moveUpRotor.
Optional_mode: "lower" | "higher"Whether the cursor moved
Intersection navigation mode is available only when the plot has
multiple lines. points is a 2-D array whose outer dimension is the line
index, so length > 1 means at least two lines exist — a prerequisite for
any crossing between sampled series to be possible — and only where
series meet at their values at all (seriesCanMeet).
Move to the next point intersection (right arrow in intersection rotor mode). Default is a no-op returning false; subclasses that advertise supportsIntersectionMode must override to provide real behavior.
Move to the previous point intersection (left arrow in intersection rotor mode). Default is a no-op returning false; subclasses that advertise supportsIntersectionMode must override to provide real behavior.
Trace implementation for contour and filled contour plots.
A scalar field drawn as curves of constant value. Structurally that is a multi-line layer -- one curve per level -- so navigation, braille and highlighting all transfer from LineTrace, and walking a row is walking one iso-value curve.
The level is a first-class object, not a colour. Read as a plain line layer, the level is a series name at best: the curve announces where it runs and never what value it runs at, which is the first thing anyone asks of a contour plot. So it is announced on the
zaxis -- the field's own axis -- where the layer'szformat applies to it, because it is a value of the field rather than a label for the curve.Spacing is the gradient. How densely the curves are drawn is the visual cue for how steeply the field changes, and it is the one thing a reader walking a single curve can never assemble: the curve says nothing about its neighbours. So each point announces the distance to the nearest point on the adjacent level, which is exactly the distance an eye measures between two lines -- tight spacing is a cliff, wide spacing is a plateau.
The lattice underneath a contour is a heatmap and Heatmap reads it, which is the fallback the issue calls the cheap one. What is here is the reading that makes the chart legible.