Scene

extends Group

The Scene class represents the top-level container in a visualization. This is where graphical objects (i.e., mark or group) are created, transformed and joined with data. To create a scene object, use the scene function:

let scene = atlas.scene();

Properties

propertyexplanationtypedefault value
fillColorthe background color of the sceneColor“white”

Properties inherited from Group

propertyexplanationtypedefault value
id the unique id of the groupString
type the type of the groupString“scene”
children the graphical objects in the groupArray[]
firstChild the first child in the groupMark or Group
bounds the bounding rectangle of the groupRectangle
center the center of the group boundsPoint

Methods: Create Mark or Group

methodexplanationreturn type
mark(type, props)create a new mark with the specified type and properties
type (String): mark type
props (Object): property names and values
Mark
group(children)create a new group with the specified children
children (Array, optional): objects to be added in the group
Group
glyph(…marks)create a new glpyh with the specified marks as children
marks (Marks): primitive marks as part of the glyph
Glyph

Methods: Join Graphics with Data

methodexplanationreturn type
repeat(item, table, params)repeat a graphical object by a field
item (Mark or Group): graphical object to be repeated
table (DataTable): data table
params (Object, optional): containing one or more of the following:
  • field (String): the field to repeat by, defaults to tuple ID
  • layout (Layout): the layout to arrange the repeated items
Collection
divide(item, table, params)divide a graphical object by a field
item (Mark or Group): graphical object to be repeated
table (DataTable): data table
params (Object, optional): containing one or more of the following:
  • field (String): the field to divide by, defaults to tuple ID
  • orientation (String): the orientation to divde the item
  • layout (Layout): the layout to arrange the divided items
Collection
densify(item, table, params)densify a graphical object by a field
item (Mark or Group): graphical object to be repeated
table (DataTable): data table
params (Object, optional): containing one or more of the following:
  • field (String): the field to densify by, defaults to tuple ID
  • orientation (String): the orientation to densify the item
Path
attach(item, table)attach the entire table to a single graphical object,
item (Mark or Group): graphical object
table (DataTable): data table
void

Methods: Encode

angle

methodexplanationreturn type
encode(item, params)encode a field using a visual channel
item (Mark or Group): an example item to be encoded
params (Object): contains the following properties
  • channel (String, required): visual channel
  • field (String, required): data field
  • aggregator (String, optional): aggregator, defaults to “sum”
  • scale (Scale, optional): scale
  • scaleType (String, optional): type of scale
  • flipScale (Boolean, optional): whether the scale is flipped,
    defaults to false
  • includeZero (Boolean, optional): whether the scale domain includes 0, defaults to false
  • rangeExtent (Number, optional): range extent
  • mapping (Object, optional): user defined mapping
  • scheme (String, optional): color scheme
  • startAngle (Number): the start angle in degrees when binding to “angle”, default to 90
  • angleDirection (String): the direction to encode angles,
    default to “clockwise”
Encoding
encodeWithinCollection
(item, params)
encode a field using a visual channel
item (Mark or Group): an example item to be encoded
params (Object): contains the following contains the following properties
  • channel (String, required): visual channel
  • field (String, required): data field
  • aggregator (String, optional): aggregator, defaults to “sum”
  • scale (Scale, optional): scale
  • scaleType (String, optional): type of scale
  • invertScale (Boolean, optional): whether the scale is inverted,
    defaults to false
  • includeZero (Boolean, optional): whether the scale domain includes 0, defaults to false
  • rangeExtent (Number, optional): range extent
  • mapping (Object, optional): user defined mapping
  • scheme (String, optional): color scheme
  • startAngle (Number): the start angle in degrees when binding to “angle”, default to 90
  • angleDirection (String): the direction to encode angles,
    default to “clockwise”
Array of Encodings

Methods: Create Guides

methodexplanationreturn type
axis(channel, field, params)create an axis
channel (String): the visual channel
field (String): the data field
params (Object, optional): contains one or more of the axis properties
Axis
legend(channel, field, params)create a legend
channel (String): the visual channel
field (String): the data field
params (Object, optional): contains one or more of the legend properties
Legend
gridlines(channel, field, params)create a set of gridlines
channel (String): the visual channel
field (String): the data field
params (Object, optional): contains one or more of the gridline properties
Gridlines

Methods: Manage and Manipulate Items

methodexplanationreturn type
classify(items, field, parent)group items by the specified field, items with the same field value
are put in the same collection
items (Array): an array of items
field (String): field to group by
parent (Scene or Collection): parent of the resulting collections
Array of Collections
find(predicates)returns graphical objects in the scene that match the specified criteria
predicates (Array): an array of predicates
Array
setProperties(item, params)set the properties for all the peers of the specified item, return an object indicating setting each property is successful.
item (Mark or Group or Layout): example item
params (Object): property names as object keys and property values as object values
{property: Boolean}
propagate(item, method, …params)call the specified method for all the peers of the specified item
item (Mark or Group): example item
method (String): name of the item’s method
params: parameters of the item’s method
e.g., scene.propagate(path, "sortVertices", "x")
void
translate(item, dx, dy)move the item by the given distance, returns an object indicating if translating along x or y is successful.
item (Mark or Group): item to move
dx (Number): number of pixels to move in the x direction
dy (Number): number of pixels to move in the y direction
{x: Boolean, y: Boolean}

Methods: Specify Constraints

methodexplanationreturn type
align(items, anchor)align the items so that they have the same position for the specified anchor
items (Array): objects to be aligned
anchor (String): anchor to align
void
affix(item, baseItem, channel, params)affix items to the specified base items in x or y direction
item (Mark): an example item
baseItem (Mark): an example base item
channel (String): “x”, “y”, “angle”, or “radialDistance”
params (Object, optional): additional parameters:
  • itemAnchor (String): anchor of item,
    defaults to “center” for “x” and “angle” channels
    defaults to “middle” for “y” and “radialDistance” channels
  • baseAnchor (String): anchor of base item,
    defaults to “center” for “x” and “angle” channels
    defaults to “middle” for “y” and “radialDistance” channels
  • offset (Number): distance between item anchor and base item anchor, defaults to 0
void

Methods inherited from Group

methodexplanationreturn type
addChild(c)adds an object to the groupvoid
addChildAt(c, i)adds an object to the group at the specified indexvoid
removeChild(c)removes the specified object from the groupvoid
removeAll()removes all the children from the groupvoid
getScene()returns the scene in which this group residesScene
sortChildren
(channel, reverse)
sort the children by a visual channel
channel (String): the channel to sort the children by
reverse: (Boolean, optional) setting to true will sort in descending order;
default is false.
void
sortChildrenByData
(field, reverse, order)
sort the children by a data field
field (String): the data field to sort the children by
reverse (Boolean, optional): setting to true will sort in descending order;
default is false.
order (Array, optional): an array of field values in ascending order
void