feat(symbol): various clipping on the symbol.

[plainheart]

Brief Information

This pull request is in the type of:

• [ ] bug fixing
• [x] new feature
• [ ] others

What does this PR do?

Add clipping support for symbol. Enhance features of the symbol, such as (1) making the image symbol rounder (2) enabling the symbol to be in various shapes

Fixed issues

• #3803
• #4124
• https://github.com/apache/echarts/issues/9495#issuecomment-443067103
• #15442

Details

Before: What was the problem?

It's not supported to make the image symbol rounder or clipped to various shapes.

After: How is it fixed in this PR?

Add a new option symbolClip to support the clipping on symbol.

Usage

Are there any API changes?

• [x] The API has been changed.

Add a new option symbolClip, which accepts the value type of string or function. The supported rules of clipping are following with basic shape of the CSS clip-path: https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path

• 'inset' / 'rect'
• 'circle'
• 'ellipse'
• 'polygon'
• 'path'
• Any basic or extended path/shape provided by ECharts, such as echarts.graphic.Sector and echarts.graphic.Ring etc.

Related test cases or examples to use the new APIs

Please refer to test/symbol-clip.html.

Others

Merging options

• [ ] Please squash the commits into a single one when merge.

Other information

A performance issue should be considered carefully, It's better to try to reuse the same clip path and avoid generating lots of duplicate paths, especially for SVG renderer. I have no good ideas for this now. Any help will be appreciated.

[echarts-bot[bot]]

Thanks for your contribution! The community will review it ASAP. In the meanwhile, please checkout the coding standard and Wiki about How to make a pull request.

The pull request is marked to be PR: author is committer because you are a committer of this project.

Document changes are required in this PR. Please also make a PR to apache/incubator-echarts-doc for document changes. When the doc PR is merged, the maintainers will remove the PR: awaiting doc label.

[pissang]

I think we don't have to implement the string expression of CSS clip-path. It's too complex and not easy to debug. Also, it's not friendly for type checking. We prefer to express the clipping by object configuration like color gradient, for example:

clipPath: { type: 'rect', shape: {xxxxx} }

I think we have similar configurations in the graphic component.

Another concern from me is that shadows may not work when using clip-path.

[plainheart]

I think we don't have to implement the string expression of CSS clip-path. It's too complex and not easy to debug. Also, it's not friendly for type checking. We prefer to express the clipping by object configuration like color gradient, for example:

clipPath: { type: 'rect', shape: {xxxxx} }

I think we have similar configurations in the graphic component.

@pissang No problem. The object configuration rule is my very first implementation scheme. But after a short time, I think it may be better to follow the CSS rule because the developers needn't make extra conversions and changes. So I made a refactor for this. If making an object for clip-path is better, I will revert the implementation and dive into it.

[pissang]

But after a short time, I think it may be better to follow the CSS rule because the developers needn't make extra conversions and changes. So I made a refactor for this.

I can totally understand it. We should follow the existing rule as much as possible. But the reason we should not use a string expression is that it's not that convenient for developers. Not like the SVG path string, which is mostly generated by Adobe Illustration. CSS expressions will be written by hand. In this case, it's hard for us to provide auto-completion and validation on a string expression in VSCode, which is not a problem for CSS.

So my suggestion is, instead of following the exact string expression, we can still use an object to express the configuration. But when naming the properties and designing possible values, we can use the existing rule as our reference.