Coordinate Systems in Apache ECharts: Cartesian, Polar, Geo, and More

Apache ECharts provides nine distinct coordinate systems—including Cartesian, Polar, Geo, Radar, Single Axis, Parallel, Calendar, Matrix, and BMap—each implemented via dedicated classes in the source tree and registered through the core registerCoordinateSystem API.

Apache ECharts is a powerful visualization library that supports multiple geometric spaces for rendering data. Understanding the available coordinate systems in ECharts is essential for selecting the right layout for your charts, whether you are plotting standard bar graphs or complex geographic visualizations. Each system is registered through the core API and backed by specific implementation files in the repository.

Core Coordinate Systems in ECharts

The most commonly used coordinate systems handle two-dimensional plotting and geographic mapping.

Cartesian 2D (Grid)

The Cartesian coordinate system is the default for most common chart types like bar, line, scatter, and heatmap. Implemented in src/coord/cartesian/Cartesian.ts, this system maps data points to X and Y axes within a rectangular grid.

Polar

The Polar coordinate system enables radial layouts for pie charts, polar bars, and polar line charts. You can find the implementation in src/coord/polar/Polar.ts, where the Polar class handles the conversion between data values and radial positions.

Geo (Geographic)

For choropleth maps and geographic scatter plots, the Geo coordinate system uses geoCreator defined in src/component/geo/geoCreator.ts. This system projects latitude and longitude coordinates onto the canvas based on configured map data.

Specialized Coordinate Systems

Beyond the core trio, ECharts provides specialized systems for unique visualization needs.

Radar

The Radar coordinate system creates spider-web style charts through the Radar class in src/component/radar/Radar.ts. This system positions data points along axes that radiate from a central point at different angles.

Single Axis

For one-dimensional visualizations like timelines or gauge-like displays, the Single Axis system uses SingleAxisModel located in src/component/singleAxis/SingleAxisModel.ts.

Parallel Coordinates

Multivariate data visualization relies on the Parallel coordinate system, implemented via parallelCreator in src/component/parallel/parallelCreator.ts. This system arranges multiple vertical axes in parallel to show relationships between dimensions.

Calendar

Time-based heatmaps utilize the Calendar coordinate system, defined in src/component/calendar/CalendarModel.ts. This system organizes data into day-by-day grid layouts matching calendar structures.

Matrix

The Matrix coordinate system provides heat-map-like layouts where each cell represents a coordinate slot. The implementation resides in src/component/matrix/Matrix.ts.

BMap (Baidu Map)

For integration with Baidu Map API, the BMap coordinate system uses BMapCoordSys defined in extension-src/bmap/bmap.ts. This extends ECharts with Chinese mapping capabilities beyond the standard Geo system.

How to Specify Coordinate Systems in Your Configuration

When creating a chart, you select the coordinate system using the coordinateSystem property in your series configuration. All systems are registered in src/extension.ts via the registerCoordinateSystem API.

option = {
    series: [
        { type: 'bar', coordinateSystem: 'cartesian2d' },
        { type: 'line', coordinateSystem: 'polar' },
        { type: 'scatter', coordinateSystem: 'geo' },
        { type: 'heatmap', coordinateSystem: 'calendar' }
    ]
};

When a component (grid, polar, geo, etc.) is defined in your option, ECharts automatically creates the corresponding coordinate-system instance and links series that request it.

Summary

• Apache ECharts supports nine coordinate systems: Cartesian, Polar, Geo, Radar, Single Axis, Parallel, Calendar, Matrix, and BMap.
• Core implementations reside in src/coord/ (Cartesian, Polar) while specialized systems are in src/component/ (Geo, Radar, etc.).
• Registration occurs through registerCoordinateSystem in src/extension.ts.
• Use the coordinateSystem property in series configuration to select the appropriate geometric space.

Frequently Asked Questions

How do I register a custom coordinate system in ECharts?

You can register a custom coordinate system by calling the registerCoordinateSystem API with a unique name and a creator class or factory function. According to the source code in src/extension.ts, this registration makes the system available throughout the chart lifecycle for series and components to reference.

Can I mix different coordinate systems in a single chart?

Yes, ECharts allows multiple coordinate systems in one chart instance by defining separate components (like grid, polar, or geo) and assigning different series to different systems via the coordinateSystem property. Each series references its target system by the registered name, such as 'cartesian2d' or 'polar'.

What is the difference between Geo and BMap coordinate systems?

The Geo coordinate system in src/component/geo/geoCreator.ts works with built-in map data and SVG paths, while the BMap system in extension-src/bmap/bmap.ts integrates specifically with the external Baidu Map JavaScript API for Chinese geographic data. Use Geo for standard maps and BMap when you need Baidu-specific features like POI search.

Which coordinate system should I use for a spider web chart?

Use the Radar coordinate system implemented in src/component/radar/Radar.ts. This system creates the characteristic spider web layout with axes radiating from a center point, making it ideal for comparing multivariate data across different categories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}