Tracker: User Feedback

[ibgreen]

A list of weaknesses in v4 docs and API based on questions and issues reported by our users. Can be addressed through API changes, better docs, FAQ articles etc.

V5/V6 API

• deck.gl setProps({layers}) doesn't trigger if same array is set. Is this desirable in non-React apps? Warning? FAQ? Layer stays in "Awaiting State" #2131
• updateTriggers, how to use? Updating getColor with updateTriggers not working #2123
• data validation for GeoJSON and Polygons would save time/catch errors for new users Polygon layer doesn't close strokes, but documentation implies it does #1992
• declarative tooltips Update layer docs regarding tooltip display #2472, [Coding] [Doc update]Tooltip code not found #1861

V4 API

ONGOING

• Better integration with luma.gl docs (See Further documentation needed #592)

UNDER CONSIDERATION

• Improve docs for updateTriggers mechanism (e.g. Using Layers See Changing colors of LineLayer #575, How to animate ArcLayer arcs individually? #633, Can't undestand how to update a layer position #643
• Improve docs for COORDINATE_SYSTEM, Documentation for positionOrigin is wrong #599, cannot get accurate position using meter offset in scatterplot #677
• Improve docs for shader project package (strongly defined semantics) radiusMinPixels does not work with COORDINATE_SYSTEM.METERS #598
• New article about data aggregation? See How to count data on hexagon? #628, HexagonLayer elevation based on getColorValue #674
• New article about WebGL blending and z-fighting? Scatterplot Layer - circle opacity on overlap? #635

UNDER CONSIDERATION

• Add more docs about event handling and Map Interactions, maybe to Interactivity (See How can I react to the user panning the map? #574)
• Docs for flow layer? We get quite a few questions, e.g. how to change the stroke width of the flow layer? #593
• Solution for create-react-app create-react-app: Identifier 'Buffer' has already been declared #624
• Antialiasing - information needed in docs (See Anti-Aliasing Not Working when using multiple monitors on Mac #573 and How to implement anti-aliasing for deck.gl layers #557)
  • Explain limitations on MacOs
  • Explain effects of WebGL context creation parameter 'antialias'.
  • Use multisampled framebuffer under WebGL2

ALL REPOS

• Search in docs Further documentation needed #592
• Explain how to run examples linked locally How to run examples with deck.gl locally linked #627
• Prebundled builds? importing deck.gl? #637

OTHER REPOS

• support for data textures? support for data textures? #632 - this should be an article in luma.gl v4 GPGPU section

OTHER

• Use with Angular Create example using deck.gl with angular2 #576, importing deck.gl? #637, how to make deck.gl work in responsive canvas? #638, Debugging picking? #640
• Use with Open Layers deck.gl可以用openLayers代替mapbox吗？  #650

[jefffriesen]

I have one suggestion on documentation for updateTriggers. Right now the docs say this:

This prop expects an object of which the keys matching the accessor names of a layer.
If any values in this object are changed between props update, the attribute corresponding
to the accessors named by the key will be invalidated.

I'm not clear what that means. I think what's missing isn't what the keys should be, it's what the values for the keys should be. I've looked through the repo and sometimes there are functions, sometimes values. Sometimes the original values don't match the value in updateTriggers. For example:

const MALE_COLOR = [0, 128, 255]
const FEMALE_COLOR = [255, 0, 128]

// later in the code...
    const layer = new ScatterplotLayer({
      id: 'scatter-plot',
      data,
      radiusScale: radius,
      radiusMinPixels: 0.25,
      getPosition: d => [d[0], d[1], 0],
      getColor: d => d[2] === 1 ? maleColor : femaleColor,
      getRadius: d => 1,
      updateTriggers: {
        getColor: {c1: maleColor, c2: femaleColor}
      }
    });

In the above case, the primary getColor returns an array of numbers. The getColor key inside updateTriggers returns an object. Not sure what c1 and c2 are in this case.

In other places, we have 2 different functions for getPosition:

      new PlotLayer({
        getPosition: (u, v) => {
          const x = (u - 1 / 2) * Math.PI * 2;
          const y = (v - 1 / 2) * Math.PI * 2;
          return [x, y, equation(x, y)];
        },
        getColor: (x, y, z) => [40, z * 128 + 128, 160],
        getXScale: getScale,
        getYScale: getScale,
        getZScale: getScale,
        uCount: resolution,
        vCount: resolution,
        drawAxes: showAxis,
        axesPadding: 0.25,
        axesColor: [0, 0, 0, 128],
        opacity: 1,
        pickable: Boolean(this.props.onHover),
        onHover: this.props.onHover,
        updateTriggers: {
          getPosition: equation
        }
      })

// where equation is:
const equation = (x, y) => {
  return Math.sin(x * x + y * y) * x / Math.PI;
};

I have a work around for this so I'm not blocked, but I think this would be important for updated documentations. updateTriggers is used in lots of examples in the repo, which indicates to me it's important (and I could use it if I understood it).

Thanks

[Pessimistress]

@jefffriesen Thanks for the feedback! I agree that we're not doing a good job explaining updateTriggers.
To unblock you, let me try to explain it here.

• Accessors such as getColor and getPosition are called to retrieve colors and positions when you first add the layer. From then on, to maximize performance, deck.gl does not recalculate colors or positions unless the data prop changes.
• Sometimes data remains the same, but the outcome of an accessor has changed. In the scatterplot example, this is caused by the user interacting with the color input. In this case, you need to explicitly inform deck.gl to re-evaluate getColor for all data items.
• You do so by defining updateTriggers. The following code:

    updateTriggers: {
        getColor: {c1: maleColor, c2: femaleColor}
    }

Says that the output of getColor is affected by two values c1 and c2. Every render cycle, deck.gl compares updateTriggers.getColor with its previous value 1-level deep (this is so that you can specify multiple dependencies). If either c1 or c2 changes, any attribute that depends on getColor will be updated.

• The "trigger" value may be a string, object or function - as long as it can be shallow-compared with the previous value.

Let me know if this helps. If so, I will add a page to documentation on this topic.

[jefffriesen]

@Pessimistress Thanks so much for helping me out on this. Some of the explanation above makes sense to me, some not.

Accessors such as getColor and getPosition are called to retrieve colors and positions when you first add the layer. From then on, to maximize performance, deck.gl does not recalculate colors or positions unless the data prop changes.

Perfectly clear and well designed

Sometimes data remains the same, but the outcome of an accessor has changed. In the scatterplot example, this is caused by the user interacting with the color input. In this case, you need to explicitly inform deck.gl to re-evaluate getColor for all data items.

Yep, someone types in a new maleColor/femaleColor value in the input box and now

getColor: d => d[2] === 1 ? maleColor : femaleColor,` 

has a different result, even though d is the same.

Says that the output of getColor is affected by two values c1 and c2.

Where did c1 and c2 come from? Are they arbitrarily-named keys? They are not in the manhattan.json data structure (which is an array of arrays). Is there some meaning with the key names or could I just call them {a: maleColor, b: femaleColor}? If that's the case, why not pass in an array like [maleColor, femaleColor]?

Every render cycle, deck.gl compares updateTriggers.getColor with its previous value 1-level deep (this is so that you can specify multiple dependencies).

It will only look 1 level deep even with nested data structures, even though in this example, getColor is returning a simple array. But I'm not clear on the multiple dependencies aspect. Multiple dependencies for what?

The "trigger" value may be a string, object or function - as long as it can be shallow-compared with the previous value.

This statement is close to helping, but I can't reconcile it with the c1 and c2 object above.

Hopefully going through and explaining this to me like I'm 5 will help out others when reading the documentation! Thanks again.

[howtimeflies0]

@jefffriesen thanks a lot for asking for clarification. This will greatly help the quality of deckgl's documentation. Please send similar feedback here or create separate issues on github when you find more unclear docs!

@Pessimistress your explanation is super clear. We should definitely put your explanation to our docs!

[Pessimistress]

@jefffriesen Think of updateTriggers.getColor as a list of dependencies that affect getColor's output - it can be {c1: maleColor, c2: femaleColor}, or {maleColor, femaleColor}, or [maleColor, femaleColor]. In fact, I like your suggestion. I think the arbitrary keys c1 c2 really threw you off there. I can update the example code.

[jefffriesen]

@Pessimistress Oh, that clears things up. I forked the repo and was looking at the code, but I guess in retrospect I should have run the example and tried different things.

I wonder if having that much flexibility in specifying update triggers is more confusing. When I was searching the code for examples, I saw several different ways of doing it. To me that was more confusing because I was trying to pick up on the pattern, whereas if it was consistent the pattern would be easier to spot. Is there a reason not to just have an array of values instead of objects with arbitrary keys?

[ericsoco]

@jefffriesen you've probably already discovered this, but this is the updateTriggers diff implementation, and it supports a single value, an array of values, or a key-value map (object). We're opting to maintain flexibility but the above PR limits the documented usage to just a value or array of values.

Thanks for the feedback!

[howtimeflies0]

I plan to create issues for each item in the list and use our newly created workboard to track them.

[ibgreen]

I plan to create issues for each item in the list and use our newly created workboard to track them.

@shaojingli Sounds good but maybe we should go through the status first, these were created a while ago.