Visual Mapping

Basic Concepts of Visual Mapping

Visual mapping is a component in ECharts used to map data values to visual elements (such as color, size, opacity, etc.). It allows users to understand data distribution and trends through intuitive visual encoding. Visual mapping is commonly used in scenarios requiring the display of continuous data variations, such as heatmaps, scatter plots, and maps.

The core idea of visual mapping is to map the numerical domain (data domain) to the visual domain (visual domain). For example, mapping a numerical range of [0, 100] to a color gradient of ['#000', '#fff'], or mapping [10, 50] to a circle size range of [5, 20].

Types of Visual Mapping

ECharts provides two main types of visual mapping:

1. Continuous Visual Mapping (continuous): Suitable for continuous numerical data.
2. Segmented Visual Mapping (piecewise): Suitable for discrete categorical data.

Example of Continuous Visual Mapping

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    inRange: {
      color: ['#50a3ba', '#eac736', '#d94e5d']
    },
    calculable: true
  },
  series: [{
    type: 'scatter',
    data: [[12, 23, 45], [34, 56, 78], [56, 78, 90]]
  }]
};

Example of Segmented Visual Mapping

option = {
  visualMap: {
    type: 'piecewise',
    pieces: [
      {min: 0, max: 50, label: '0-50', color: '#93CE07'},
      {min: 50, max: 100, label: '50-100', color: '#FBDB0F'},
      {min: 100, max: 150, label: '100-150', color: '#FC7D02'}
    ]
  },
  series: [{
    type: 'scatter',
    data: [[12, 23, 45], [34, 56, 78], [56, 78, 120]]
  }]
};

Detailed Configuration of Visual Mapping

Visual mapping offers rich configuration options to precisely control the mapping relationship from data to visual elements:

Basic Configuration

• type: Specifies the type of visual mapping ('continuous' or 'piecewise').
• min/max: Defines the data range.
• dimension: Specifies the index of the data dimension.
• seriesIndex: Specifies the associated series index.

Visual Channel Configuration

Visual mapping supports mapping for various visual channels:

1. Color Mapping:

inRange: {
  color: ['#121122', 'rgba(3,4,5,0.4)', 'red']
}

2. Size Mapping:

inRange: {
  symbolSize: [10, 70]
}

3. Opacity Mapping:

inRange: {
  opacity: [0.3, 1]
}

4. Symbol Type Mapping:

inRange: {
  symbol: ['circle', 'rect', 'diamond']
}

Interaction Configuration

The visual mapping component supports rich interactive features:

visualMap: {
  // Display drag handles
  calculable: true,
  // Real-time updates
  realtime: true,
  // Orientation (horizontal or vertical)
  orient: 'horizontal',
  // Position
  left: 'right',
  top: 'bottom'
}

Advanced Applications of Visual Mapping

Multi-Dimensional Visual Mapping

ECharts supports simultaneous visual mapping for multiple data dimensions:

option = {
  visualMap: [
    {
      type: 'continuous',
      dimension: 0,
      inRange: {
        color: ['red', 'blue']
      }
    },
    {
      type: 'continuous',
      dimension: 1,
      inRange: {
        symbolSize: [10, 40]
      }
    }
  ],
  series: [{
    type: 'scatter',
    data: [[12, 23, 45], [34, 56, 78], [56, 78, 90]]
  }]
};

Custom Mapping Functions

For more complex mapping requirements, use formatter to customize the mapping logic:

visualMap: {
  type: 'continuous',
  formatter: function (value) {
    return 'Value: ' + value.toFixed(2);
  },
  inRange: {
    color: function(value) {
      return value > 50 ? '#ff0000' : '#0000ff';
    }
  }
}

Visual Mapping with Data Zooming

Visual mapping can be combined with the dataZoom component to achieve dynamic range adjustment:

option = {
  dataZoom: [
    {
      type: 'slider',
      xAxisIndex: 0
    }
  ],
  visualMap: {
    type: 'continuous',
    dimension: 2,
    min: 0,
    max: 100,
    inRange: {
      color: ['blue', 'green', 'yellow', 'red']
    }
  },
  series: [{
    type: 'scatter',
    data: [...]
  }]
};

Applications of Visual Mapping in Different Charts

In Maps

Visual mapping is commonly used in maps to display regional data:

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    text: ['High', 'Low'],
    realtime: false,
    calculable: true,
    inRange: {
      color: ['#e0f3f8', '#abd9e9', '#74add1', '#4575b4', '#313695']
    }
  },
  series: [{
    type: 'map',
    map: 'china',
    data: [
      {name: 'Beijing', value: 80},
      {name: 'Shanghai', value: 90},
      {name: 'Guangdong', value: 70}
    ]
  }]
};

In Heatmaps

Heatmaps are a classic application scenario for visual mapping:

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 10,
    inRange: {
      color: ['#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8', '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026']
    }
  },
  series: [{
    type: 'heatmap',
    data: [
      [0, 0, 5], [0, 1, 7], [0, 2, 3],
      [1, 0, 4], [1, 1, 2], [1, 2, 8],
      [2, 0, 6], [2, 1, 9], [2, 2, 1]
    ]
  }]
};

In Scatter Plots

Scatter plots often use visual mapping to display multi-dimensional data:

option = {
  visualMap: [
    {
      type: 'continuous',
      dimension: 2,
      min: 0,
      max: 100,
      inRange: {
        color: ['blue', 'red']
      }
    },
    {
      type: 'continuous',
      dimension: 3,
      min: 0,
      max: 50,
      inRange: {
        symbolSize: [5, 30]
      }
    }
  ],
  series: [{
    type: 'scatter',
    dimensions: ['x', 'y', 'value', 'size'],
    data: [
      [10, 20, 30, 15],
      [15, 25, 70, 25],
      [20, 30, 50, 40]
    ]
  }]
};

Performance Optimization for Visual Mapping

When dealing with large-scale data, visual mapping may impact performance. Here are some optimization suggestions:

1. Reduce the number of visual channels: Only map necessary visual attributes.
2. Use discrete mapping: For large datasets, segmented mapping performs better than continuous mapping.
3. Limit the data range: Set reasonable min/max values.
4. Disable real-time updates: Set realtime: false.

// Optimized configuration example
visualMap: {
  type: 'piecewise',
  categories: ['Low', 'Medium', 'High'],
  inRange: {
    color: ['#1e90ff', '#ffa500', '#ff4500']
  },
  realtime: false,
  splitNumber: 5  // Reduce the number of segments
}

Style Customization for Visual Mapping

ECharts allows deep customization of the visual mapping component's style:

Controller Style

visualMap: {
  type: 'continuous',
  // Controller background
  backgroundColor: '#ccc',
  // Text style
  textStyle: {
    color: '#333',
    fontSize: 12
  },
  // Handle style
  handleStyle: {
    color: '#fff',
    borderColor: '#666'
  },
  // Indicator style
  indicatorStyle: {
    color: '#999'
  }
}

Legend Style

visualMap: {
  type: 'piecewise',
  // Legend position
  left: 'center',
  top: 'top',
  // Legend item style
  itemGap: 10,
  itemWidth: 20,
  itemHeight: 14,
  // Legend text format
  formatter: function (value) {
    return 'Range: ' + value;
  }
}

Interaction Events for Visual Mapping

ECharts provides rich event support for visual mapping:

myChart.on('selectchanged', function(params) {
  console.log('Selection range changed:', params.selected);
});

myChart.on('highlight', function(params) {
  console.log('Highlighted:', params.dataIndex);
});

myChart.on('lowlight', function(params) {
  console.log('Unhighlighted:', params.dataIndex);
});

// Programmatic control
myChart.dispatchAction({
  type: 'selectDataRange',
  visualMapIndex: 0,
  selected: [20, 50]
});

Integration of Visual Mapping with Themes

Visual mapping can seamlessly integrate with the ECharts theme system:

// Register a custom theme
echarts.registerTheme('myTheme', {
  visualMap: {
    inRange: {
      color: ['#ffc0cb', '#800080']
    },
    textStyle: {
      color: '#fff'
    }
  }
});

// Apply the theme
var myChart = echarts.init(dom, 'myTheme');

Responsive Design for Visual Mapping

Visual mapping can adapt to different screen sizes with responsive configurations:

option = {
  visualMap: {
    type: 'continuous',
    orient: window.innerWidth > 500 ? 'horizontal' : 'vertical',
    left: window.innerWidth > 500 ? 'right' : 'center',
    top: window.innerWidth > 500 ? 'bottom' : 'top'
  }
};

window.addEventListener('resize', function() {
  myChart.setOption({
    visualMap: {
      orient: window.innerWidth > 500 ? 'horizontal' : 'vertical'
    }
  });
});