Multi-axis Shapes

[alexshoe]

Description:

Extends xref and yref to accept arrays, allowing shapes to span multiple subplots with each vertex anchored to a different axis. See #7151 for more information.

Example:

shapes: [{  
  type: 'rect',  
  x0: 0, 
  x1: 1, 
  y0: 0, 
  y1: 1,  
  xref: ['x', 'x2'],  // x0 uses 'x', x1 uses 'x2'  
  yref: ['y', 'y2']   // y0 uses 'y', y1 uses 'y2'
}]

Progress:

• Step 1: Attributes & validation
  • Extend xref and yref to allow array values
  • Add helper function to check number of defining coordinates of a shape
  • Update value validation to work with array values
• Step 2: Refactor coordinate conversion
• Step 3: Update shape rendering
• Step 4: Addressing editable shapes
• Step 5: Tests + documentation

[emilykl]

a more intuitive function signature here would be function(shapeType, path) I think

[emilykl]

Hmm. H and V segments cause an odd usability issue I hadn't considered: if a path contains H and V segments then the expected lengths of xref and yref may be different, and the corresponding list items will be "out of sync" with respect to which path segments they correspond to (i.e. it will not always be the case that xref[n] and yref[n] refer to the same path segment).

For example here is a rectangular path: M0,0H10V5H0Z (see visualization)

There are four segments (not counting Z), but only 3 x-values and 2 y-values are needed to define the shape. So you would have:

{
    "path": "M0,0H10V5H0Z",
    "xref": ["x", "x2", "x"],
    "yref": ["y", "y2"],
}

which is a bit odd, and sort a high cognitive load for the user to figure out the right xref and yref lists.

That said, it seems probably better than the other alternative that comes to mind, which would be to force the user to add an xref and a yref for every single segment, even if it will be ignored for some segments.

[emilykl]

dflt and extraOption should probably be arguments to this function

[emilykl]

Should probably raise a warning in both of these cases

[emilykl]

Hmm, unless I'm missing something I think you want to use the logic from axes.coerceRef here: var axlist = gd._fullLayout._subplots[axLetter + 'axis'];

Because you don't just want to check if it's theoretically a valid axis reference; you want to check if it corresponds to an axis that actually exists in the plot.

[emilykl]

The core Lib.coerce() function uses more complex logic here for setting the attribute in the out container -- I'm not 100% sure whether that's needed here, but something to verify.

[emilykl]

I don't think this is needed, since anywhere in the codebase where getRefType() would be called on an array probably needs a whole separate code path to handle ref arrays.