LabelSpec

Source: Label.ts

Text label appearance and placement. Pixel sizes are logical display pixels;
resolution increases texture detail without changing the displayed size.
Create labels with GLViewer.addLabel and update them with GLViewer.setLabelStyle.

Example

Screen and world anchors with different texture resolutions

CODE
viewer.addModel().addAtoms([
  {elem: "C", x: -2, y: 0, z: 0}, {elem: "O", x: 2, y: 0, z: 0}
]);
viewer.setStyle({}, {sphere: {radius: 0.7}});
// The two world labels follow the model when the view rotates.
[1, 3].forEach(function(resolution, i) {
  viewer.addLabel("world: " + resolution + "x", {
    position: {x: -2 + i * 4, y: -1.1, z: 0}, alignment: "topCenter",
    fontSize: 16, resolution: resolution, backgroundColor: "navy"
  });
  // Higher texture resolution sharpens text without enlarging the label.
  viewer.addLabel("screen: " + resolution + "x", {
    position: {x: 16, y: 16 + i * 34, z: 0}, useScreen: true,
    fontSize: 16, resolution: resolution, backgroundColor: "darkgreen"
  });
});
viewer.zoomTo();
viewer.rotate(25, "z");
viewer.render();

Instance Fields

alignment: string | object

how to orient the label w/respect to position: "topLeft" (default),
"topCenter", "topRight", "centerLeft", "center", "centerRight",
"bottomLeft", "bottomCenter", "bottomRight", or an arbitrary x,y alignment vector

Properties

  • x (number)
  • y (number)

backgroundColor: ColorSpec

color of background, default black

backgroundGradient: GradientSpec | GradientType

left-to-right background gradient, used instead of backgroundColor

backgroundHeight: number

minimum label height in pixels when backgroundImage is set; omitted or zero uses the image height

backgroundImage: any

An image to draw into the label. Any CanvasImageSource is allowed. The label expands to fit the image.

backgroundOpacity: number

opacity of background, default 1.0

backgroundWidth: number

minimum label width in pixels when backgroundImage is set; omitted or zero uses the image width

bold: boolean

render text in bold, default false

borderColor: ColorSpec

color of border, default backgroundColor

borderOpacity: number

Border opacity; defaults to the background opacity.

borderThickness: number

line width of border around label, default 0

font: string

font name, default sans-serif

fontColor: ColorSpec

font color, default white

fontOpacity: number

font opacity, default 1

fontSize: number

font size in pixels, default 18

frame: number

If set, display only when the viewer is on this zero-based animation frame.

inFront: boolean

always put labels in front of model, default true

padding: number

padding around text in pixels; defaults to 4 when omitted or zero

position: XYZ

Label anchor in world coordinates (angstroms), or screen pixels when useScreen is true. GLViewer.addLabel can also position a label at the center of a selection.

resolution: number

Texture pixels per label pixel (default 2). Must be a finite number at least 1; invalid values use 2. Larger values increase texture memory.

screenOffset: object

x,y pixel offset of label from position

Properties

  • x (number)
  • y (number)

showBackground: boolean

show background rounded rectangle, default true

useScreen: boolean

position uses screen coordinates: x and y are pixel offsets from the upper left corner; z is clamped to [0,1]