Declarative styling

[pjcozzi]

Short-Term

Spec

@ggetz

• [ ] Better name than "3D Tiles Style"
• [ ] Hackathon to experiment with current version

@pjcozzi

• [x] TODOs in spec
• [x] Finish spec and schema

  Cesium Implementation

@ggetz

• [x] Latest schema for color map and color ramp
  • Remove BooleanExpression, NumberExpression, and friends
  • Unit tests: Cesium3DTileStyle (and implicitly for Cesium3DTileStyleEngine)
• [x] Load style from uri, not just JSON string.
• [x] Pass styleEngine last to constructors (and make it optional?)
• [x] Example evaluating a style/expression on pick
• [x] Remove chroma - 18d80354be225a116d0a711bb79b190871a82534 and e7aebcddacdcdcc00bb5120215d7f248a5acb29a (and ColorRampExpression.computeEvenlySpacedIntervals)

@pjcozzi

• [x] Reference doc
• [x] Update CHANGES.md
• [x] Run coverage and see if we are missing any tests for 3D Tiles styles

---

Later

Spec

• [ ] Add JulianDate datatype to support styling with date/time metadata
• [ ] Introduce translucency property to assign to without having to set RGB?
  • [ ] And/or built-in variables to get the feature's current color and show?
• [x] Operator overloads for regular expressions (we already overload for Color so why not here?), see https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/2#issuecomment-184332713
• [ ] Allow variable names inside member expressions, eg. ${foo[${memberName}]}
• [x] Non-visual properties, e.g., for infobox display, e.g.

{
    "show" : true,
    "color" : [255, 255, 255],
    "meta" : {
        "description" : "Hello, ${FeatureName}"
    }
}
var str = style.meta.description.evaluate(feature);

• [ ] Escape variables in strings.
• [ ] In general, is the ability to assign to feature properties in the style (as part of the JSON or maybe expression) useful?
  • [ ] Improved "standard library"
• [x] Cesium built-in math functions, e.g., distance
• [ ] Check out GLSL
  • [ ] Built-ins like GLSL, e.g., czm_time, czm_inShadow, etc.
  • [ ] Include GLSL in a style?
  • [ ] Cascading multiple styles on one tileset?
  • [ ] Add explicit interval to optimize conditional when used for intervals
  • [ ] Referencing other features in a style

color : ramp(palette, distance(${thisFeature.location}, ${anotherFeature.location}))

show : (${thisFeature.height} > ${anotherBuilding.height})

• [ ] Multiple expressions in conditions, https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/2#issuecomment-191754803
• [ ] Generate reference doc from JSON schema
• [ ] Core styling schema + extensions for buildings, vector data, point clouds, etc.?
• [ ] Influence from CZML, i.e., time-dynamic styles
  • [ ] Integration with Cesium Property system, e.g., evaluate expressions as Property or vice-versa.
• [ ] Other style languages, e.g., more like CSS selectors
• [x] Support vector and matrix properties since this is supported in the batch table binary.
• [ ] Bounding volume hierarchy information (https://github.com/AnalyticalGraphicsInc/cesium/issues/4654)
  • [ ] Tile bounding volumes
  • [ ] Level in tree
• [x] Support vector types like vec2, vec3, and vec4
• [x] Allow component-wise math operations similar to GLSL

Cesium Implementation

• [ ] Interfaces for Cesium3DTileStyle and friends for users writing their own styles.
• [ ] Fix jsep to allow for single backslash characters to be parsed correctly. Workaround is to replace before jsep for now.
• [ ] Column numbers for syntax errors
• [ ] Use regex and replace function for replaceVariables in Expression.js?
• [x] GPU implementation for tile formats that would really benefit, e.g., point clouds
• [ ] Line width (can we make this as simple as a uniform/batch-value and not recreate geometry?)
• [ ] Expose AST?
• [ ] Expose Conditional properties?
• [ ] Apply to GeoJSON?
• [ ] Optimizations if needed: constant folding and dead code elimination
• [ ] Schema validation - how much do we do at runtime? Tool for offline validation?
• [ ] Style features in parallel

Built-in functions

• [x] radians(x) - convert value to radians
• [x] degrees(x) - convert value to degrees
• [x] cos(x)
• [x] sin(x)
• [x] tan(x)
• [x] asin(x)
• [x] acos(x)
• [x] atan(x)
• [x] atan2(y,x) - atan(y,x) in GLSL
• [x] pow(x,y)
• [x] sqrt(x)
• [x] abs(x)
• [x] sign(x)
• [x] floor(x)
• [x] ceil(x)
• [x] round(x)
• [x] min(x,y)
• [x] max(x,y)
• [x] clamp(x,y,z)
• [x] mix(x,y,a)
• [x] length(x)
• [x] distance(x,y)
• [x] dot(x,y)
• [x] cross(x,y)
• [x] normalize(x)
• [ ] random - 0.0 to 1.0 (some complexity on the GLSL side)
• [x] exp(x)
• [x] log(x)
• [x] exp2(x)
• [x] log2(x)
• [x] fract
• [x] time
• [x] Consider data-driven implementation to avoid lots of duplication where the only difference is the function name and number of arguments.

[pjcozzi]

I will add this to the roadmap.

Also, some useful info is here: http://stackoverflow.com/questions/4719320/new-number-vs-number

[pjcozzi]

@ggetz here's some notes for when you are ready to integrate the new expressions into the style JSON schema.

• All the various show options go away, and show is always a string with an expression that evaluates to Boolean.
• color can be a string with an expression that evaluates to Color or an object for a color map or ramp (replacing the highlighted code here).

Here's a map:

"color" : {
    "key" : "RegEx('^1(\\d)$').exec(${id})",
    "map" : {
        "1" : "Color('#FF0000')",
        "2" : "Color('#00FF00')"
    },
    "defaultValue" : "Color('#FFFFFF')"
}

Note that the value in each pair in the map (e.g., "Color('#FF0000')") is an expression evaluating to a Color so it could include variables, etc.

Likewise, I'm pretty sure we will want the key in each pair to also be an expression (kinda like you had before), and we can optimize the case where all keys in the map are literals by building the hash lookup at compile time.

For "color ramps" or "intervals", I think it is best to start with a generic set of conditionals that we execute like a series of if...else statements, e.g.,

"color" : {
    "key" : "${Height} / ${Area}",
    "conditional" : {
        "(${KEY} >= 1.0)  && (${KEY} < 10.0)"  : "Color('#FF00FF')",
        "(${KEY} >= 10.0) && (${KEY} < 30.0)"  : "Color('#FF0000')",
        "(${KEY} >= 30.0) && (${KEY} < 50.0)"  : "Color('#FFFF00')",
        "(${KEY} >= 50.0) && (${KEY} < 70.0)"  : "Color('#00FF00')",
        "(${KEY} >= 70.0) && (${KEY} < 100.0)" : "Color('#00FFFF')",
        "(${KEY} >= 100.0)"                    : "Color('#0000FF')",
    }
}

key could be optional (or even not part of the schema, but it adds a nice readability and easy optimization for complete expressions). Each conditional property has an expression that evaluates to Boolean and an expression that evaluates to Color.

This approach allows a lot of flexibility and avoids a bunch of schema for closed/open intervals; however, it isn't well suited to a binary search for evaluation (it is basically a linear search). Optimizing it would require a bunch of analysis; later, if we need, we could just introduce an interval schema.

Note that these color maps and ramps could be implemented completely in an expression with the ternary operator, but it would be ugly, painful to generate, and harder to optimize at runtime.

[ggetz]

For "color ramps" or "intervals", I think it is best to start with a generic set of conditionals that we execute like a series of if...else statements

Aren't a map and ramp pretty much the same thing? For example, you can express the "map" in "ramp" syntax pretty easily if we add "defaultValue":

"color" : {
    "key" : "RegEx('^1(\\d)$').exec(${id})",
    "conditional" : {
        "${key} === 1" : "Color('#FF0000')",
        "${key} === 2" : "Color('#00FF00')"
    },
    "defaultValue" : "Color('#FFFFFF')"
}

[pjcozzi]

I actually had that at one point, but made them separate so it would be easy to optimize maps with all literals, e.g., build the hash (JavaScript object) at compile time. However, I think it is still pretty easy to do the same compile-time analysis with conditional (just look for === LITERAL for all properties). Give it a shot!

[pjcozzi]

@ggetz I tightened up the spec in 20d820105127cc3282ca523764c5ae0275547898. Can you please review?

A few questions:

• Does our RegExp type have a toString() function like Color? It should.
• We need to explain how operators work with RegExp (even if we just disable them for now). For example, colors say this:

Colors support the following binary operators by performing component-wise operations: ===, !==, +, -, *, /, and %. For example color() === color() is true since the red, green, blue, and alpha components are equal.

• It's fine to say the following, but we also need to document the arguments like we do for Color, isNaN, etc.

The regExp function behaves like the JavaScript RegExp constructor and takes the same arguments.

• Can you add a statement to the variables section like 'Variables can be used anywhere an expression can be used except...' or can they be used everywhere (in which case, we should make that explicit)?

[pjcozzi]

@ggetz to organize things, I moved our task lists from https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/2#issuecomment-180355858 and https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/2#issuecomment-183918785 to the top comment: https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/2#issue-88423282

[ggetz]

Does our RegExp type have a toString() function like Color? It should.

Not an explicit function, I will add one.

We need to explain how operators work with RegExp (even if we just disable them for now). For example, colors say this:

I would say operators do not work with RegExp at all for now.

I'll add the other items to the spec as well.

[ggetz]

Also the changes in 20d8201 look good.

[pjcozzi]

@ggetz I stepped through the code in Expression.js and made some minor tweaks in https://github.com/AnalyticalGraphicsInc/cesium/commit/10c8c9f914a718cf1660bd7dd1133f6529752966

Here's a few questions/TODOs:

• [x] Check over all the try blocks and only do the part of the code that might throw instead the try block.
• [x] Does _evaluateLiteralString need to call replaceBackslashes? Can we do this at compile time instead?
• [ ] Can we do the instanceof checks in _evaluatePlus at compile time, e.g., so we will end up with more _evaluate functions but they will be optimized for their particular type instead of doing type checking at runtime. If it helps make things clean in the compile step, we could even do a first pass over the AST to compute type info, then a second pass to generate the runtime AST. Not sure that the extra pass is necessary though.
• [x] All of the calls to new Color (like in _evaluatePlus) will be bad for performance. Can we make color.evaluate take a result parameter (see styleContent in Cesium3DTileStyleEngine.js) and use scratch variables?

[pjcozzi]

@ggetz test coverage for Expression.js is pretty good at 98%. Can you please add tests for the DeveloperErrors that are not covered to bring coverage up to 100%?

[ggetz]

Can we do the instanceof checks in _evaluatePlus at compile time, e.g., so we will end up with more _evaluate functions but they will be optimized for their particular type instead of doing type checking at runtime.

I'm guessing this would apply to all of the arithmetic _evaluate functions?

[ggetz]

Also we could do some of the instanceof checks at compile time, but we would need to leave one evaluate function with the instanceof checks in at runtime because of expressions where the types are not clear until evaluation, for example ${myColor} + 3 * color('red')

[pjcozzi]

I'm guessing this would apply to all of the arithmetic _evaluate functions?

Yes.

Also we could do some of the instanceof checks at compile time, but we would need to leave one...

OK.

[ggetz]

Should we wait for the optimized evaluate functions? I believe they are currently on the roadmap under "Later".

[pjcozzi]

Should we wait for the optimized evaluate functions?

Will it be significantly time consuming or significantly deteriorate the code quality? If not, I would do it now. If so, then we can evaluate later.

[ggetz]

If it's targeted to the operators involving Colors, it shouldn't be too time consuming.

[pjcozzi]

@ggetz did you add key to https://github.com/AnalyticalGraphicsInc/cesium/pull/3655 as suggested in https://github.com/AnalyticalGraphicsInc/3d-tiles/issues/2#issuecomment-187728554?

For example:

"color" : {
    "key" : "${Height} / ${Area}",
    "conditional" : {
        "(${KEY} >= 1.0)  && (${KEY} < 10.0)"  : "color('#FF00FF')",
        "(${KEY} >= 10.0) && (${KEY} < 30.0)"  : "color('#FF0000')",
        "(${KEY} >= 30.0) && (${KEY} < 50.0)"  : "color('#FFFF00')",
        "(${KEY} >= 50.0) && (${KEY} < 70.0)"  : "color('#00FF00')",
        "(${KEY} >= 70.0) && (${KEY} < 100.0)" : "color('#00FFFF')",
        "(${KEY} >= 100.0)"                    : "color('#0000FF')"
    }
}

If not, can you please add it and name it expression since key came from the map terminology?

[pjcozzi]

Also, what do you think of renaming conditional in the schema to conditions, e.g.,

"color" : {
    "expression" : "RegEx('^1(\\d)$').exec(${id})",
    "conditional" : {
        "{$EXPRESSION} === 1" : "color('#FF0000')",
        "{$EXPRESSION} === 2" : "color('#00FF00')",
        "true" : "color('#FFFFFF')"
    }
}

becomes

"color" : {
    "expression" : "RegEx('^1(\\d)$').exec(${id})",
    "conditions" : {
        "{$EXPRESSION} === 1" : "color('#FF0000')",
        "{$EXPRESSION} === 2" : "color('#00FF00')",
        "true" : "color('#FFFFFF')"
    }
}

[pjcozzi]

@ggetz did you add key to AnalyticalGraphicsInc/cesium#3655 as suggested in #2 (comment)?

Also, later, we could consider expanding key/expression into an object that could hold multiple expressions for complex conditions, e.g.,

    "color" : {
        "expressions" : {
            "id" : "RegEx('^1(\\d)$').exec(${id})",
            "area" : "${length} * ${height}"
        },
        "conditions" : {
            "({$ID} !== 1) && (${AREA} > 0)" : "color('#FF0000')"
        }
    }

This is overkill for now, but let's consider it if experience shows it will be useful.

[ggetz]

"Expression" and "conditions" sound good. For expression, I think ${expression} is more straight forward than {$EXPRESSION} because it looks like the other variables.

I do like the idea of multiple expressions as well.

[pjcozzi]

I think ${expression} is more straight forward than {$EXPRESSION} because it looks like the other variables.

OK.

Also, this will override a property named expression so, in that case, they need to use feature.expression.

I do like the idea of multiple expressions as well.

OK, let's add it when we need it.

[pjcozzi]

I do like the idea of multiple expressions as well.

Also, I already updated the roadmap for this.

[ggetz]

Also, I already updated the roadmap for this.

OK thanks.

[pjcozzi]

First cut of the spec is in #80.

[ggetz]

First cut of the spec is in #80.

OK

[ggetz]

Suggestions for new name:

• 3D Tiles Ink
• 3D Tiles Flux
• 3D Tiles Chalk
• 3D Tiles Pigment
• 3D Tiles Embellish
• 3D Tiles Flourish

[twpayne]

tl;dr The current specification for conditions requires JSON object property order to be preserved, which is rarely true.

JavaScript's for ... in statement iterates over object properties in an arbitrary order. The popular Java library org.json defines a JSON object as "an unordered collection of name/value pairs". Iteration order over Golang maps (a common internal representation for JSON objects) is randomized.

Concrete example: Styling/README.md contains the example

{
    "show" : "${Area} > 0",
    "color" : {
        "conditions" : {
            "${Height} < 60" : "color('#13293D')",
            "${Height} < 120" : "color('#1B98E0')",
            "true" : "color('#E8F1F2', 0.5)"
        }
    }
}

A feature with property Height == 0 matches all three conditions, and therefore its computed color will depend entirely on the evaluation order of the conditions.

Generating conditions objects automatically will also be problematic, as some languages and libraries do not allow the order of properties in the serialized JSON output to be controlled.

Suggestion: either require that all conditions are mutually exclusive (tricky to enforce) or replace the conditions object with an ordered Array of [condition, value] pairs (uglier, but well defined).

[pjcozzi]

Good eye, @twpayne! I'm surprised we haven't ran into this issue in practice already.

replace the conditions object with an ordered Array of [condition, value] pairs (uglier, but well defined).

+1 for this.

@lilleyse is it reasonable for you to make this change (code and spec) as part of your current point cloud declarative styling work?

[lilleyse]

@lilleyse is it reasonable for you to make this change (code and spec) as part of your current point cloud declarative styling work?

Yes it should be easy to change. For the spec I'll open a separate PR for this fix. For the code I'll make the change in my styling PR.

[pjcozzi]

Yes it should be easy to change. For the spec I'll open a separate PR for this fix. For the code I'll make the change in my styling PR.

In https://github.com/AnalyticalGraphicsInc/cesium/pull/4336/commits/5cb1088d0dbc8b01d2eb46b289e1ab77150c01b1, part of https://github.com/AnalyticalGraphicsInc/cesium/pull/4336.

[pjcozzi]

Labeling draft 1.0 just for the utility functions and finishing the vector types.

[pjcozzi]

@ggetz is there anything here critical for 1.0?

[ronanmcnulty]

Is there anyway to color based on whether the lat & lng are within a polygon?

[ggetz]

@ronanmcnulty It sounds like classification might fit your use case better.

[ThornM9]

Thanks for the input, @pierotofy. We definitely want to support custom functions for expressions, and, I agree, will most likely go with the concise syntax. Thanks for the code snippets!

Were custom functions for expressions ever implemented @pjcozzi ? I'm attempting to color a point cloud by elevation but there's no height attribute for point clouds.

[pjcozzi]

@ThornM9 no but there may be another way to achieve your use case, the best place to ask is the Cesium forum: https://groups.google.com/forum/?hl=en#!forum/cesium-dev

[conradlempert]

I noticed that atan2(y,x) is more inaccurate than atan(y/x). (While atan(y/x) only works for x > 0 of course). In my particular use case I used the atan2 function to compute the longitude of points in the tileset.

The resulting longitude from atan2(y, x) was off by about 0.00001 (ca. 10 meters), while it looked perfect with atan(y/x).

Unfortunately I don't know how to tell you the exact resulting numbers since they are only in the GPU I guess, I can only give this estimate from what it looks like.

My cesium version is 1.63, however this was reproducable in a sandcastle.

Sandcastle: https://sandcastle.cesium.com/#c=lVX7TyM3EP5XRtFJbErq7CabB081B7SNRAGRcKeTIiFnd0JcHDu1vYSA+N873kcIHHdqfyCsxzPfN283m1daKAcnUmcpTNdwZfSMwRU6NDCQElUDTrTMFlPB4UaJBzRWuDVc66l2IrFwzqcMRglXSqg7DzCQ+DdXqdEwNjpJtBRAR/iLOxRwInTCjRTIJuqBG3gQuCKiI1C4ghO0IluwL7ksmNSS/HyileNCoZnUGvA8UQDkmiEJefogUjT7lWFikEi+aiPTcaES1BsT9VI/mKiCzgmJFt1bvuJf+3RcXAY5R2bkBneo1TVanZkE2czoxcCS2jANom7cijYMRSjMJqiQLY1YCEfZsoynaVDyFo4kWlkHKVonFHdCK3LnnXnCF2g4IxOfjMKjLYP9N+5z4+iLq3bg1QDiOIx6ccy6cRzFnXYUNwp5q9UJOxGLo7DX34uisNMqL+LOXiduhazdi3v9OG63vbieX2ojkNL/HemfyFOq95VwyfxaS1lSd4i022u3+2EnbO/1Or2S4deQtXrdbtiLOu1+e6/f75YXXdbqR+RLv9eJwzDsdyrqsmhl4hhVNl1TwRfCInNzVMEsU4l3a5PbojeK5C7znj6q6s2mOlPe39FyjobSSzGhyQmgbEFGIipYWa/nwjsgIOr2PPgcsvEqp9M+bPRymXhEORJPuA9R2Ni+oSHQr2164k/s+vLb4Pzz+c3ZG81UWD6VeIpLNx9TwU+FdVwlBHlBI0huXl2OhuPhl7Pb4cXvw4vh+Ftl/eI/8qwB+L9mE4Zwr/QK3Jw7+hEW7gUNop6B1OpOuCzFpqTS+g9ycbHMikIDaSrtgEZ9DUuDCeW8UULO9QpJDmudAc08WMQCXzigX4mcsi+1vreVJcw0zd0cX0nfcK2Em5MlV8G6+VhnJc1AWt3wmHauM0l7Ccntmd8uVE/rGcnS064wdyGvahW5H3RD7SlG/2TcYEp9UGb+TEqxtFqk7Osfo37MbrXCSwrnekv7oIJQ2iy4pHKmV2U37WxEwQMm7eDTc1GNy4vbwefR5fnN+OyFPcIvsAO7bzwg4S7sNLx8u9iw8yHC+iOE9f9BePoI4ckj1Os7B9t52hRlQCXwe6iW12JSI+X3CdilW7Zu/vjusT6pHXyI3NpAt36G3fgP2BW+dWuJBFuOYIozeiPs1khSG13jUvIE3/uS99zbyH0DgdNlPyPN4WxGIpq8Cm6jv/8ObjO/1Szt+1Ct+FkWnyiawuylNKdGX3nDT88b9Bc4hhwi2Nr0+s7w5Vwk+UO0Wf1Bvo/qbGNbz7dBnrBqB1YJ+8HLN/LXQa5ULZF8m9QatcNcelzF+ZtYLLVx/okMGGs6XFCWyY/mNEvuiSixtkAAOGxumx6m4gFEevTByw6J5NbSzSyT+Q6d1I4Pm6T/nanU+cvjx1bytVebR8fnhZAxdtik48eWTms55eYd8r8

[lilleyse]

See https://github.com/CesiumGS/3d-tiles/issues/179 for optimizing large number of conditional expressions.

[lilleyse]

See https://github.com/CesiumGS/3d-tiles/issues/239 for batching vector images into a texture atlas that's part of the payload

[lilleyse]

See https://github.com/CesiumGS/3d-tiles/issues/252 for mutables (like GL uniforms)

[lilleyse]

See https://github.com/CesiumGS/3d-tiles/issues/266 for styling alpha separately

[lilleyse]

See https://github.com/CesiumGS/3d-tiles/issues/268 for accessing feature ids in the styling language

[lilleyse]

See https://github.com/CesiumGS/3d-tiles/issues/292 for accessing instanced attributes in the styling language

[lilleyse]

More considerations for 3D Tiles Next:

• Can styles access metadata at different granularities including tileset, tile, and group metadata. We support this in CesiumJS.
• Do properties need to be fully qualified based on their class id? e.g. ${classId.propertyId}? Or only when there are collisions?
• Can property textures be styled? Would styling need to happen on the GPU in this case?
• Should geometry attributes like position, normal, etc be available as built-ins and not just for point clouds?
• Do styles have access to statistics?
• Do styles have access to class min/max properties values? Both are needed to do color ramps. Statistics are good for localized color ramps, class min/max is good for global color ramps (think a color ramp from the Mariana trench to Everest)
• Do styles have access to enums? ${buildingType} === BuildingType.HOSPITAL