echarts-instance/coordinates

101 notes in this subject, read out of this brain and free to use. This is page 2 of 2.

coordinateSystem 'matrix' option details

When coordinateSystem is set to 'matrix', the series or component is laid out based on a matrix coordinate system. When multiple matrix coordinate systems exist within an ECharts instance, the corresponding system must be specified using matrixIndex or matrixId.

coordinateSystemUsage property options and defaults

The coordinateSystemUsage property specifies how to lay out a series or component based on the specified coordinateSystem. Valid options are 'data' (each data item of a series is laid out separately based on the coordinate system; only supported by series, not non-series components) or 'box' (the entire series or component is laid out as a whole, with its layout rectangle or anchor point calculated relative to the system). The default value is 'data' for series and 'box' for non-series components. In most cases there is no need to specify coordinateSystemUsage unless the default behavior is unexpected.

coordinateSystemUsage 'data' mode behavior

When coordinateSystemUsage is set to 'data', each data item of a series (for example, each series.data[i]) is laid out separately based on the specified coordinate system. Currently no non-series component supports coordinateSystemUsage: 'data'. Most series such as series-line, series-bar, and series-scatter only support this mode.

coordinateSystemUsage 'box' mode behavior

When coordinateSystemUsage is set to 'box', the entire series or component is laid out as a whole based on the specified coordinate system—the overall bounding rect or basic anchor point is calculated relative to the system. For example, a grid component can be laid out in a matrix or calendar coordinate system where its layout rectangle is calculated by the coordinateSystemUsage and coords. A pie series or chord series can be laid out in a geo or cartesian2d coordinate system where the center is calculated by the specified coords or center in that system.

coordinateSystem property options

The coordinateSystem property specifies which coordinate system a series or component is laid out on. Valid options are: 'cartesian2d' (rectangular Cartesian coordinate system, also called grid), 'polar' (polar coordinate system), 'geo' (geographic coordinate system), 'singleAxis' (single-axis coordinate system), 'parallel' (parallel coordinate system), 'calendar' (calendar coordinate system), 'matrix' (matrix coordinate system), or null/undefined/'none' to disable coordinate system layout and instead lay out independently.

coord property with coordinateSystemUsage 'box'

When coordinateSystemUsage is set to 'box', the coord property is used as input to the coordinate system to calculate the layout rectangle or anchor point. The format of coord is defined by each coordinate system and is the same as the second parameter of chart.convertToPixel(). Note that when coordinateSystemUsage is 'data', the input to the coordinate system is series.data[i] rather than this coord.

xAxisId property

xAxisId is a number property with default value undefined. It specifies the id of the xAxis to base on. When multiple xAxis components exist within an ECharts instance, use this to specify the corresponding xAxis.

yAxisIndex property

yAxisIndex is a number property with default value 0. It specifies the index of the yAxis to base on. When multiple yAxis components exist within an ECharts instance, use this to specify the corresponding yAxis.

yAxisId property

yAxisId is a number property with default value undefined. It specifies the id of the yAxis to base on. When multiple yAxis components exist within an ECharts instance, use this to specify the corresponding yAxis.

polarIndex property

polarIndex is a number property with default value 0. It specifies the index of the polar coordinate system to base on. When multiple polar coordinate systems exist within an ECharts instance, use this to specify the corresponding polar.

polarId property

polarId is a number property with default value undefined. It specifies the id of the polar coordinate system to base on. When multiple polar coordinate systems exist within an ECharts instance, use this to specify the corresponding polar.

singleAxisIndex property

singleAxisIndex is a number property with default value 0. It specifies the index of the singleAxis coordinate system to base on. When multiple singleAxis coordinate systems exist within an ECharts instance, use this to specify the corresponding singleAxis.

singleAxisId property

singleAxisId is a number property with default value undefined. It specifies the id of the singleAxis coordinate system to base on. When multiple singleAxis coordinate systems exist within an ECharts instance, use this to specify the corresponding singleAxis.

geoIndex property

geoIndex is a number property with default value 0. It specifies the index of the geographic coordinate system to base on. When multiple geographic coordinate systems exist within an ECharts instance, use this to specify the corresponding geographic. For series-map, when geoIndex and geoId are not specified, the map series creates an exclusive geo component for itself. geoIndex or geoId can be used to specify an outer geo component, which can be shared with other series like pie. Moreover, the region color of the outer geo component can be controlled by the map series via visualMap. When geoIndex or geoId is specified, series-map.map and other style configurations like series-map.itemStyle will not work, but corresponding configurations in the geo component will be used.

geoId property

geoId is a number property with default value undefined. It specifies the id of the geographic coordinate system to base on. When multiple geographic coordinate systems exist within an ECharts instance, use this to specify the corresponding geographic. For series-map, when geoIndex and geoId are not specified, the map series creates an exclusive geo component for itself. geoIndex or geoId can be used to specify an outer geo component, which can be shared with other series like pie. Moreover, the region color of the outer geo component can be controlled by the map series via visualMap. When geoIndex or geoId is specified, series-map.map and other style configurations like series-map.itemStyle will not work, but corresponding configurations in the geo component will be used.

parallelIndex property

parallelIndex is a number property with default value 0. It specifies the index of the parallel coordinate system to base on. When multiple parallel coordinate systems exist within an ECharts instance, use this to specify the corresponding parallel.

parallelId property

parallelId is a number property with default value undefined. It specifies the id of the parallel coordinate system to base on. When multiple parallel coordinate systems exist within an ECharts instance, use this to specify the corresponding parallel.

calendarIndex property

calendarIndex is a number property with default value 0. It specifies the index of the calendar coordinate system to base on. When multiple calendar coordinate systems exist within an ECharts instance, use this to specify the corresponding calendar.

calendarId property

calendarId is a number property with default value undefined. It specifies the id of the calendar coordinate system to base on. When multiple calendar coordinate systems exist within an ECharts instance, use this to specify the corresponding calendar.

matrixIndex property

matrixIndex is a number property with default value 0. It specifies the index of the matrix coordinate system to base on. When multiple matrix coordinate systems exist within an ECharts instance, use this to specify the corresponding matrix.

matrixId property

matrixId is a number property with default value undefined. It specifies the id of the matrix coordinate system to base on. When multiple matrix coordinate systems exist within an ECharts instance, use this to specify the corresponding matrix.

Series and component coordinate system support table

The following table shows which series and components can be laid out on which coordinate systems: grid (cartesian2d) supports: grid, polar, line, bar, pie, scatter, effectScatter, boxplot, candlestick, heatmap, map, lines, graph, chord, pictorialBar; polar supports: polar, line, bar, pie, scatter, effectScatter, lines, graph, chord; geo supports: geo, pie, scatter, effectScatter, heatmap, map, lines, graph, chord; singleAxis supports: singleAxis, pie, scatter, effectScatter, lines, themeRiver; radar supports: radar; parallel supports: parallel, series-parallel; calendar supports: calendar (grid, polar, geo, singleAxis, calendar, tree, treemap, sunburst, map, graph, sankey, funnel, gauge, title, legend, dataZoom, visualMap, toolbox, timeline, thumbnail); matrix supports: matrix (grid, polar, geo, singleAxis, tree, treemap, sunburst, map, graph, sankey, funnel, gauge, title, legend, dataZoom, visualMap, toolbox, timeline, thumbnail); no coordinate system supports: grid, polar, geo, singleAxis, calendar, matrix, pie, tree, treemap, sunburst, map, sankey, funnel, gauge, graph (with 'view' coord sys), chord, title, legend, dataZoom, visualMap, toolbox, timeline, thumbnail.

Series coordinateSystemUsage support matrix

Most series only support coordinateSystemUsage: 'data', such as series-line, series-bar, series-scatter. Some series only support coordinateSystemUsage: 'box', such as series-pie, series-tree, series-treemap, series-sankey. Only a few series support both modes, including series-graph and series-map.

Coordinate systems in echarts

ECharts provides multiple coordinate systems: Cartesian coordinate system (grid), polar coordinate system (polar), GEO coordinate system (geo), single axis coordinate system (singleAxis), and calendar coordinate system (calendar). Series like line, bar, scatter, and heatmap require a coordinate system. Series like pie and tree work independently without a coordinate system. Series like graph can work independently or on a coordinate system depending on configuration.

Cartesian coordinate system composition

A Cartesian coordinate system consists of xAxis, yAxis, and grid components. The grid is the baseboard that references and assembles the xAxis and yAxis to work cooperatively. ECharts can create a grid implicitly when only xAxis, yAxis, and a series are declared.

Multiple axes and series configuration

Multiple axes of the same type can be configured in a single echarts instance (e.g., two yAxis with one xAxis). Series can reference specific axes using properties like yAxisIndex and xAxisIndex. Multiple grid instances can coexist, each with its own xAxis and yAxis, referenced using gridIndex property.

Series compatibility across coordinate systems

A series type is typically available on various coordinate systems. For example, a scatter series can work on Cartesian, polar, GEO, or other coordinate systems. Similarly, a coordinate system can serve multiple series types, such as a Cartesian coordinate system serving both line and bar series.

convertToPixel method signature

convertToPixel(finder: {...}, coord: [...] | number, opt?: unknown) => [number, number] | number converts coordinates in various coordinate systems to pixel values relative to the chart container's top-left corner [0, 0]. The finder parameter specifies which coordinate system or axis to use. The coord format and return type depend on the coordinate system.

convertToPixel finder parameter options

The finder object in convertToPixel can specify coordinate system using: xAxisIndex/xAxisId/xAxisName, yAxisIndex/yAxisId/yAxisName, gridIndex/gridId/gridName, polarIndex/polarId/polarName, geoIndex/geoId/geoName, singleAxisIndex/singleAxisId/singleAxisName, calendarIndex/calendarId/calendarName, matrixIndex/matrixId/matrixName, seriesIndex/seriesId/seriesName.

convertToPixel for cartesian2d (grid)

For cartesian2d/grid coordinates: input coord is [x, y] where types depend on axis.type. For 'value' or 'log' axes, use [number, number]. For 'category' axes, use [(number | string), ...] where string is from series.data and number is the index. For 'time' axes, use [(number | string | Date), ...] where number is timestamp and string/Date are parsed by echarts date parser.

convertToPixel for geo coordinates

For geo coordinates: input coord can be [number, number] representing [longitude, latitude] for GeoJSON or [x, y] for SVG, or a string representing the name property in GeoJSON features or a named element in SVG. Returns pixel coordinates of that location or region center.

convertToPixel for single axis

For singleAxis coordinates: input coord is a single value (number or string) depending on axis.type, similar to only xAxis or only yAxis. Returns a single number representing the pixel position.

convertToPixel for calendar

For calendar coordinates: input coord is (number | string | Date) where number is timestamp and string/Date are parsed by echarts date parser. Examples: '2021-01-01', new Date(1609459200000), or 1609459200000 timestamp.

convertToPixel for matrix

For matrix coordinates: input coord locates a rectangle and returns its center point. Can specify coordinates as [coord1, coord2] for individual cells or [[coord1, coord2], [coord3, coord4]] for range spanning multiple cells. Coordinates can be strings (axis names) or numbers (ordinal indices from 0).

convertToLayout method signature

convertToLayout(finder: {calendarIndex?, calendarId?, calendarName?, matrixIndex?, matrixId?, matrixName?}, coord: [...] | number, opt?: unknown) => {rect?, contentRect?, matrixXYLocatorRange?} converts coordinate system coords to layout information. Available from version 6.0.0. Supports calendar and matrix coordinate systems.

convertToLayout for calendar return value

convertToLayout for calendar returns {rect: {x, y, width, height}, contentRect: {x, y, width, height}}. The rect is the cell rectangle without considering borders (adjacent cells are adjacent). The contentRect is the rect minus borders.

convertToLayout for matrix return value

convertToLayout for matrix returns {rect: {x, y, width, height}, matrixXYLocatorRange: [[minXOrdinal, maxXOrdinal], [minYOrdinal, maxYOrdinal]]}. The rect is the cell rectangle. The matrixXYLocatorRange is the ordinal range for the result.

convertToLayout matrix clamp option

convertToLayout matrix supports opt.clamp parameter: 0/null/undefined (default) means no boundary restriction (result may be NaN), 1 clamps to entire coordinate system range, 2 clamps to body range, 3 clamps to corner range. X and Y are calculated independently.

convertToLayout matrix ignoreMergeCells option

convertToLayout matrix supports opt.ignoreMergeCells parameter (default false). When true and result rectangle intersects merged cells, the result rectangle is expanded to completely cover the merged cells.

convertFromPixel method signature

convertFromPixel(finder: {...}, value: [number, number] | number, opt?: unknown) => [number, number] | [[number, number], [number, number]] | number converts pixel values to logical coordinates. It is the inverse operation of convertToPixel. The finder parameter specifies the coordinate system. The value is pixels relative to container top-left [0, 0].

containPixel method signature

containPixel(finder: {...}, value: Array) => boolean determines whether a given pixel point is within a specified coordinate system or series. Supported on: grid, polar, geo, matrix, series-map, series-graph, series-pie.

Give your agent this brain