Support multi-line labels

[mramato]

This came up on the forum a while ago and the thread was recently revived to see if we had support yet.

I think it should be possible to do by detecting new line breaks and calculating a y offset in addition to the x offset we already calculate. @shunter is this as easy as it sounds or am I missing something?

[andr3nun3s]

Hey, I'd like to implement this and would like more details.

After a quick look I think I'd need to change LabelCollection.js, but what exactly? Do I add the y-offset calculation to the repositionAllGlyphs function? What else would need to be changed?

Let me know, thanks.

[mramato]

I think that's exactly what you need to do. There might be more to it than that, but we probably won't know until we try. It might turn out to be pretty simple.

[andr3nun3s]

It seems that @abwood had a working initial implementation. I hope there's no problem in me using this commit abwood@689a166 as a starting point, right now it looks like this:

Should the label be completely above the billboard? Looks like the computed y offset is not enough.

[mramato]

Awesome, yes, starting with @abwood's code is fine in this case.

Where the text ends up is dependant on the vertical origin setting. Look at the documentation for vertical origin here: http://cesiumjs.org/Cesium/Build/Documentation/Label.html#verticalOrigin there's also a useful picture.

The offset by distance stuff is probably getting in the way here, so I wouldn't use it for your testing. Here's some example code you can use instead. If the verticalOrigin is "bottom" text should grow "up" and if the origin is top, text should grow "down". And when origin is center, text should be at the center of position.

var viewer = new Cesium.Viewer('cesiumContainer');

viewer.entities.add({
    position : Cesium.Cartesian3.fromDegrees(0,0,0),
    point : {
        pixelSize : 5
    },
    label : {
        text : 'Center'
    }
});

viewer.entities.add({
    position : Cesium.Cartesian3.fromDegrees(0,0,0),
    point : {
        pixelSize : 5
    },
    label : {
        text : 'Top',
        verticalOrigin : Cesium.VerticalOrigin.TOP
    }
});

viewer.entities.add({
    position : Cesium.Cartesian3.fromDegrees(0,0,0),
    point : {
        pixelSize : 5
    },
    label : {
        text : 'BOTTOM',
        verticalOrigin : Cesium.VerticalOrigin.BOTTOM
    }
});

viewer.zoomTo(viewer.entities);

[andr3nun3s]

It seems to be working pretty well:

Should I write some unit tests? Can you give me an example on how to test this one?

Thanks

[mramato]

Awesome. You can probably reach into the LabelCollection and verify that it generated the billboards with the expected pixelOffsets. Feel free to open the PR for review whenever you like and mention that you still need to add tests.

[pjcozzi]

Fixed in #4306.