From Apache OpenOffice Wiki
Jump to: navigation, search

Shape Gradient MS2003 Filter Enhancement

Specification Status
Author Jianyuan Li
Last Change See wiki history
Status draft



Reference Document Check Location (URL)
Issue ID (required) available Issue 119498
Test case specification (required) n/a


Role Name E-Mail Address
Developer Jianyuan Li
Quality Assurance nobody
Documentation nobody
User Experience nobody

Basic gradient concept comparison between AOO and MS

Basic gradient concept comparison between AOO and MS is as follows:

MS2003 AOO



Color 1

From color

Color 2

To color


Center XY

Fill to




Below is an example gradient which helps explain concepts above:

Gradient type.jpg
                                             Two sample gradients
The left one is ShadeShape gradient and the right one is ShadeScale gradient. For more details, see the introduction for Type.
Type: Below table show a mapping relationship between MS 2003 and AOO gradient type. For AOO other types Radial, Elliptical and Square will be mapped like Rect.

AOO MS2003 Meaning
ShadeScale A gradient fill that starts on the outline of the shape and ends at a point defined within the shape. The fill angle is scaled by the aspect ratio of the shape
Rect ShadeCenter
A gradient fill that starts and ends based on the bounds of the shape
A gradient fill that starts on the outline of the shape and ends at a point defined within the shape

Colors: For color dynamic changed (not predefined) gradient, there are only two variant color “Color 1”/”From color” and “Color 2”/”To color”. They can be set as any color. In above picture, both gradient from color and to color is blue and black.
Focus/Center XY: MS focus is a signed integer value that specifies the relative position of the last color in the shaded fill. It is defined only for ShadeScale type. AOO Center XY is a relative position (0 ~ 100) of the center rectangular of rect gradient per the origin point of a shape. Above right gradient shape’s focus is 100.
Fill to: There are left, right, top and bottom “fillTo”. The fillToLeft property specifies the relative position of the left boundary of the center rectangle in a concentric shaded fill. It is defined for ShadeCenter and ShadeShape. Above left gradient shape’s “Fill to” for the four directions are all 0.5.
Angle: For MS 2003, angle property specifies the angle of the shaded fill that rotates the gradient vector in a counterclockwise direction and will be represented with minus number. Zero degree represents a vertical vector from bottom to top. For AOO, it is also a counterclockwise direction while it will be represented with a positive number between 0~360.

Detailed Specification

Basic gradient category support from 36% to 100%
Blow shows UI for selecting gradient category according to shading style in MS 2003.
Gradient category.jpg
                       MS 2003 UI for gradient
Below is a comparison between original shapes(left) and AOO import result(right) for gradient types:
All Types MS.jpg Right arrow.jpg All Types MS Import.jpg
     Original gradients in MS 2003                                                           AOO imported gradients
For MS 2003, 22 gradient categories are supported. But only 8 gradient categories can be imported correctly. In this feature, all other categories will be supported both for import and export of MS 2003 filter. Due to feature gap for shape gradient between MS 2003 and AOO, from color and to color need be swapped in some conditions. AOO does not support “Focus” and “FillTo” which will impact the gradient color position. So they should be considered on import. “Center XY” does not supported by MS 2003 which will impact gradient export. Angle is supported both by MS 2003 and AOO. But how to represent a counterclockwise angle is not the same. So above properties will be considered when import and export to obtain a correct result.

Rotated gradient with shape rotation
In MS 2003, shape gradient can be rotated with shape rotation. It can be set in below UI:
Rotate with shape.jpg
                           Rotated gradient UI
Below is a comparison between original shapes(left) and AOO import result(right) for rotation:
Rotate MS.jpg Right arrow.jpg Rotate import.jpg
     Original gradients in MS 2003                                     AOO imported gradients
MS 2003 support whole gradient will be rotated when a shape is rotated whole AOO does not. If this property is not considered, all gradient type will be imported incorrectly. In this feature, the shape rotated angle will be taken as part of gradient angle to keep the fidelity. There are two points which should be kept in mind. One is clockwise and counterclockwise will impact the import result. The other is to make clear that rotation angle and gradient angle relationship -- plus or minus. When export, just export the gradient angle will be okay.

Transparency gradient
Below is a comparison between original shapes(left) and AOO import result(right) for transparency:
Transparency MS.jpg
                         Original gradients in MS 2003
Transparency Import.jpg
                            AOO imported gradients
For transparency, there is no feature gap. Now only from color is imported and to color is ignored. So the import and export result will be in chaos. In this feature, to color will be taken into consideration and a new item “XFillFloatTransparenceItem” (for basic color transparency, the item is “XFillTransparenceItem”) will set into core function to set gradient transparency. This item should be considered to get the correct output result on export.

Solid transparency gradient
In AOO, a special gradient can be created with using gradient related item. It can be constructed with solid color and transparency item. This can be set with below UI in AOO:
Solid gradient.jpg
                          AOO UI for solid gradient
Below is a comparison between original shapes(left) in AOO and AOO export result(right):
SolidTrans aoo.jpg Right arrow.jpg SolidTrans export.jpg
     Original gradients in AOO                                              AOO Export result
Transparency item can contain some gradient info like normal gradient in AOO. But related info will not be saved into the same item as normal gradient in document mode. So when export, this special situation must be considered. What needs to be is just set from and to color as the same color as solid color on export. Transparency related data can be obtained in transparency item.

Touched code

To implement this feature, below files(functions) need be touched:
Import: msdffimp.cxx(DffPropertyReader::ApplyFillAttributes) and related calls for it.
Export: escherex.cxx(EscherPropertyContainer::CreateGradientProperties, EscherPropertyContainer::CreateFillProperties) and related calls for them.
About how to implement related function, please refer to MS 2003 specification document "[MS-ODRAW].pdf" in page 189~213

Open Issues

For shapeCenter type, it will be imported as bitmap other than gradient. The effect looks pretty good and it can be changed with shape rotation. I have tried imported as a gradient. The effect is changed a lot when import. So here I want to just keep it. But there is an open issue. Its transparency will be handled as one color transparency. Only from color transparency is imported. Even if both from and to color transparency is considered for import, export also cannot work as expected because MS 2003 does not support this scenario (Bitmap with two color transparency).

Personal tools