Home > three_d.js

three_d.js: documentation

The first part of this page lists the various properties that define and customise the plot; there is also a list of various functions for more detailed manipulation, often of individual points.

Compulsory properties of the object passed to three_d.make_scatter()

div_id

TypeString.
DefaultNone; must be specified.
NotesCompulsory. It is the id of the <div> element that will contain the plot.

data

TypeArray of objects, one object per data point.
DefaultNone; must be specified.
NotesCompulsory. Each data point object must contain x, y, and z properties, all numbers. It may also contain properties for size (number), color (either a CSS string or numeric colour), label (string), group (integer or string), and other (usually an object).

The values can be accessed later (e.g., from a mouse event) from the input_data object that gets associated with each point, e.g. by plots[i_plot].points[i].input_data.x.

Compulsory properties of the object passed to three_d.make_surface()

div_id

TypeString.
DefaultNone; must be specified.
NotesCompulsory. It is the id of the <div> element that will contain the plot.

data

TypeAn object.
DefaultNone; must be specified.
NotesCompulsory. The object must have a property x being an array of the x-values in the grid; y an array for the y-values; and z an array of arrays for the z-values. If the length of x is nx, and the length of y is ny, then z must have length nx, and each entry of z must be an array of length ny.

Optional properties of data are color and other, both of which must have the same dimensions as z. For color, entries are either numerical colour values or CSS colours; for other, entries are objects.

The values can be accessed later (e.g., from a mouse event) from the input_data object that gets associated with each point, e.g. by plots[i_plot].mesh_points[i][j].input_data.x.

Optional properties of the object passed to either three_d.make_scatter() or three_d.make_surface()

axis_color

TypeEither a CSS string or numeric colour.
Default0xFFFFFF.
NotesThe colour of the edges of the box.

axis_font_color

TypeCSS string or numeric colour.
Default"#FFFFFF".
NotesColour of the axis titles.

axis_font_size

TypeNumber (in pixels).
Default30.
NotesFont size for the axis titles.

axis_length_ratios

TypeArray of three numbers.
Default[1, 1, 1].
NotesProportional world-space lengths of the sides of the box in the x-, y-, and z-directions.

axis_tick_gaps

TypeArray of three numbers.
Default[0.1, 0.1, 0.1].
NotesThe distance from the axis to place the tick values, in world-space coordinates (where by default the edges of the box run from -1 to 1).

axis_title_gaps

TypeArray of three numbers.
Default[0.3, 0.3, 0.3].
NotesDistance from the axis to place the axis titles, in world-space coordinates (where by default the edges of the box run from -1 to 1).

axis_titles

TypeArray of three strings.
Default["x", "y", "z"].
NotesTitles for the x-, y-, and z-axes.

background_color

TypeCSS string or numeric colour.
Default"#000000".
NotesBackground colour of the plot.

camera_r

TypeNumber.
Default5.
NotesRadius of the sphere on which the camera moves, in world-space coordinates (where by default the edges of the box run from -1 to 1).

dynamic_axis_labels

TypeBoolean.
Defaultfalse.
NotesSays whether or not the axis titles and ticks should jump to the side of the box closest to camera. On the default setting with a perspective view type, the axis titles may be hidden behind the data points when looking from the wrong side of the box, and setting this property to true should make the titles visible in this case. But I find the constant movement of the titles to be distracting, so it's false by default.

fallback_image

TypeString.
DefaultNone.
NotesAn image to use in place of the plot when the browser is not WebGL enabled, either a path to file or base64-encoded. The default behaviour is the text "Sorry, you do not have WebGL enabled." I don't know what fraction of users this is relevant for; I am more concerned about WebGL-enabled browsers crashing because my code isn't cross-platform compatible.

font

TypeString.
Default"Arial, sans-serif".
NotesThe font to use for all text in the plot.

fov

TypeNumber.
Default47.25.
NotesInitial field of view for the perspective camera in degrees.

grid_color

TypeA CSS string or numeric colour.
Default0x808080.
NotesColour of the grid lines.

height

TypeNumber (in pixels).
DefaultCalculated so that the plot is the largest square that fits in the parent <div> element.
Notes

init_camera_origin

TypeArray of three numbers.
Default[0, 0, 0].
NotesThe centre of the sphere on which the camera moves, in world-space coordinates (where by default the edges of the box run from -1 to 1). The centre moves when panning.

init_camera_rot

TypeNumber.
Default0.
NotesThe rotation (in radians) applied to the camera after it is in the position defined by init_lonlat, i.e., the roll.

init_lonlat

TypeArray of two numbers.
Default[-three_d.tau/8, three_d.tau/8].
NotesThe initial longitude and latitude (in radians) of the camera, which moves on the surface of a sphere, looking towards its centre. A lonlat of [0, 0] will position the camera on the positive x-axis.

max_fov

TypeNumber.
Default90.
NotesThe maximum field of view allowable, in degrees. Zooming is simply changing the field of view, so this property sets a limit on how far you can zoom out.

max_pan_distance

TypeNumber.
DefaultHalf the camera_r value.
NotesThis sets a limit on how far you can pan.

min_fov

TypeNumber.
Default1.
NotesThe minimum field of view allowable, in degrees. Zooming is simply changing the field of view, so this property sets a limit on how far you can zoom in.

null_width

TypeNumber.
Default1.
NotesIf the minimum and maximum of the data for some axis are the same, then this property will extend the range of the data so that the axis has length null_width.

null_width_time

TypeNumber.
Default60000.
NotesIf the minimum and maximum of the data for a time axis are the same, then this property will extend the range of the data so that the axis has length null_width_time milliseconds.

num_ticks

TypeArray of three integers.
Default[4, 4, 4].
NotesThe (approximate) number of ticks to use on the x-, y-, and z-axes. The d3.ticks function tries to pick "pretty" numbers to set the tick values, and the resulting number of ticks may not be exactly the numbers in this property.

ortho_right

TypeNumber.
DefaultCalculated to be equivalent to the perspective fov.
NotesAn orthographic camera's view extent is defined by planes; the left and right planes are defined by -ortho_right and +ortho_right respectively. (They then get rotated as the camera rotates.)

ortho_top

TypeNumber.
DefaultSet based on the aspect ratio of the plot and ortho_top if the latter is specifed; set based on the perspective fov if not.
NotesAn orthographic camera's view extent is defined by planes; the top and bottom planes are defined by +ortho_top and -ortho_top respectively. (They then get rotated as the camera rotates.)

same_scale

TypeArray of three booleans.
Default[false, false, false].
NotesThe entries of the array correspond to the x-, y-, and z-axes. Entries that are true will have consistent length scales, with the longest of them filling out to [-1, 1] in world space. This property will only be relevant if at least two entries are true.

show_axis_titles

TypeBoolean.
Defaulttrue.
NotesSays whether or not to show the axis titles (may still be switched on or off from the toggle).

show_box

TypeBoolean.
Defaulttrue.
NotesSays whether or not to show the axes box (may still be switched on or off from the control toggle).

show_grid

TypeBoolean.
Defaulttrue
NotesSays whether or not to show the grid lines (may still be switched on or off from the control toggle).

show_snaps

TypeBoolean.
Defaulttrue.
NotesSays whether or not to show the snap options ("Reset" and the snap to axis).

show_ticks

TypeBoolean.
Defaulttrue.
NotesSays whether or not to show the axis ticks (may still be switched on or off from the control toggle).

show_toggles

TypeBoolean.
Defaulttrue.
NotesSays whether or not to show the control toggles.

tick_font_color

TypeCSS string or numeric colour.
Default"#FFFFFF".
NotesColour of the tick values.

tick_font_size

TypeNumber (in pixels).
Default28.
NotesFont size for the tick values.

tick_formats

TypeArray of three strings.
Default["", "", ""].
NotesFormat strings, as used by d3.format or d3.timeFormat, for the x-, y-, and z-axis tick values. If equal to "", the code uses some d3 functions to guess an appropriate number of significant figures. For no formatting on a particular axis, set the entry to "none".

tick_lengths

TypeArray of three numbers.
Default[0.03, 0.03, 0.03].
NotesThe lengths of the ticks on each axis (in world-space coordinates, where the edges of the box by default range from -1 to 1).

time_axis

TypeArray of three booleans.
Default[false, false, false].
NotesSays whether the x-, y-, and/or z-axes have date/time values. If so, data values must be JavaScript Date objects.

view_type

TypeString.
Default"perspective".
NotesEither "perspective" or "orthographic".

width

TypeNumber (in pixels).
DefaultCalculated so that the plot is the largest square that fits in the parent <div> element.
Notes

x_scale_bounds

TypeArray of two numbers.
DefaultCalculated from the range of the data, extended by 10% on each side.
NotesDefines the lower and upper x values of the edges of the box parallel to the x-axis. Data points may be drawn outside the box.

x_tick_values

TypeArray of numbers.
DefaultCalculated by d3.
NotesThis will manually set tick values for the x-axis.

y_scale_bounds

TypeArray of two numbers.
DefaultCalculated from the range of the data, extended by 10% on each side.
NotesDefines the lower and upper y values of the edges of the box parallel to the y-axis. Data points may be drawn outside the box.

y_tick_values

TypeArray of numbers.
DefaultCalculated by d3.
NotesThis will manually set tick values for the y-axis.

z_scale_bounds

TypeArray of two numbers.
DefaultCalculated from the range of the data, extended by 10% on each side.
NotesDefines the lower and upper z values of the edges of the box parallel to the z-axis. Data points may be drawn outside the box.

z_tick_values

TypeArray of numbers.
DefaultCalculated by d3.
NotesThis will manually set tick values for the z-axis.

Optional properties of the object passed to three_d.make_scatter()

click

TypeFunction.
DefaultNone.
NotesThe function to call when the user clicks or taps on a point. The precise definition of a click is not quite the same as the standard JavaScript click event. Usually defined like params.click = function(i_plot, i, d) { ... }, where i_plot will be the index of the plot on the page (necessary to call various helper functions), i is the index of the point in the dataset, and d is an object that contains the input_data that was sent in the form of data when making the scatter plot.

connect_points

TypeBoolean.
Defaultfalse unless geom_type == "none", in which case it is automatically true.
NotesSays whether or not to draw lines between points.

custom_point

TypeString.
DefaultNone.
NotesIf the point_type is "custom", then the custom_point property says which image to use to display the data points; the property should either be a path to the file or base64-encoded like "data:image/png;base64, iVBORw0KGgo...". The image should be square with side lengths a power of 2, though I don't think it will crash if you deviate from this. Regardless of where any transparency in the image is, label positioning and mouse events will assume that is is the same size as the default sphere.

default_color

TypeEither a CSS colour string or a numeric colour.
Default0xFFFFFF.
NotesThe colour of the points, if not specified by the color property in its data point object.

default_point_height

TypeNumber (in pixels).
Default20.
NotesUsed in the absence of a size property in the data point object.

geom_type

TypeString.
Default"quad".
NotesEither "quad", "point", or "none". The latter will draw only lines between points, and not the points themselves. Of quads and points, points should be more efficient, but they have a maximum size that is GPU-dependent, so if you want to show even moderately large points (more than 50 pixels tall), then it is safest to stay with the default "quad". Also, by default points will disappear entirely from the plot once their centre is out of view; to avoid this behaviour, set the hidden_margins property to true (though this might (??) cause its own issues on some devices).

groups

TypeArray of objects, one object per group.
DefaultNone.
NotesEach object must contain a name property, which should match the group property in the input data where relevant. Optional properties are default_color, default_point_height, point_type, and custom_point, all of which have their usual meanings but can be set independently for each group.

hidden_margins

TypeBoolean.
Defaultfalse.
NotesIf geom_type is set to "point" and hidden_margins is true, then the plot area will be invisibly extended so that points do not disappear from the screen when their centre leaves the view. This might (??) cause issues on some devices.

label_font_size

TypeNumber (in pixels).
Default16.
NotesFont size for the labels attached to the data points.

max_point_height

TypeNumber (in pixels).
Default25.
NotesNot necessarily a maximum – this height will be attained by a data point whose size is equal to size_scale_bound, which by default is the maximum of the data, but which may be over-ridden.

mouseout

TypeFunction.
DefaultNone.
NotesThe function to call when the mouse leaves a point. Usually defined like params.mouseout = function(i_plot, i, d) { ... }, where i_plot will be the index of the plot on the page (necessary to call various helper functions), i is the index of the point in the dataset, and d is an object that contains the input_data that was sent in the form of data when making the scatter plot.

mouseover

TypeFunction.
DefaultNone.
NotesThe function to call when the mouse moves over a point. Usually defined like params.mouseover = function(i_plot, i, d) { ... }, where i_plot will be the index of the plot on the page (necessary to call various helper functions), i is the index of the point in the dataset, and d is an object that contains the input_data that was sent in the form of data when making the scatter plot.

point_type

TypeString.
Default"sphere".
NotesThe image to use to display the data points. The data points are not rendered as 3D objects (this is too computationally and memory-intensive), but rather as flat 2D images that are rotated so that they always face the camera. Choices other than the default are "square", "square_outlined", "triangle", "circle", "cross", "plus", and "custom". In the latter case, you must also supply an image (either path to file or base64-encoded) to the custom_point parameter.

show_labels

TypeBoolean.
Defaulttrue.
NotesSays whether or not to show the labels when first loaded. Subsequent changes must be made in the code; there is no control toggle for the labels.

size_exponent

TypeNumber.
Default2.
NotesDefines how the height of the points scale with the size values in the data point objects. The default value of 2 means that the area is proportional to the size; a value of 0 will make all points the same size.

size_scale_bound

TypeNumber.
DefaultThe maximum size value of the data point objects.
NotesThe lower bound of the size scale is always zero; this property is the size value which will be shown as max_point_height pixels tall.

Optional properties of the object passed to three_d.make_surface()

click

TypeFunction.
DefaultNone.
NotesThe function to call when the user clicks or taps on a point. The precise definition of a click is not quite the same as the standard JavaScript click event. Usually defined like params.click = function(i_plot, i, j, d) { ... }, where i_plot will be the index of the plot on the page (necessary to call various helper functions), (i, j) is the index of the point in the grid, and d is an object that contains the input_data that was sent in the form of data when making the plot.

color_scale

TypeString or function.
Default"viridis".
NotesIf the data object does not have a color property (with dimensions the same as z), then the surface will be coloured by z-value, using the colour scale specified in color_scale. Built-in scales are "inferno", "magma", "plasma", "viridis" (all from the the viridis set), and "grayscale" (or "greyscale"). If set to a function, then the function should take a single argument (assumed to be between 0 and 1), and return an array of three numbers, each between 0 and 1, corresponding to red, green, and blue channels.

color_scale_bound

TypeArray of two numbers.
DefaultThe minimum and maximum of z in the input data.
NotesDefines the z-values beyond which the colours will be the extremes of the colour scale.

hide_mesh_x

TypeBoolean.
Defaultfalse
NotesHides the mesh lines in the x-direction.

hide_mesh_y

TypeBoolean.
Defaultfalse
NotesHides the mesh lines in the y-direction.

mesh_color

TypeEither a CSS string or numeric colour.
DefaultEither black or white, depending on the background colour.
NotesThe colour of the mesh if it is set to a constant value (by the uniform_mesh_color property which is by default true).

mouseout

TypeFunction.
DefaultNone.
NotesThe function to call when the mouse leaves a point. Usually defined like params.mouseout = function(i_plot, i, j, d) { ... }, where i_plot will be the index of the plot on the page (necessary to call various helper functions), (i, j) is the index of the point in the grid, and d is an object that contains the input_data that was sent in the form of data when making the plot.

mouseover

TypeFunction.
DefaultNone.
NotesThe function to call when the mouse moves over a point. Usually defined like params.mouseover = function(i_plot, i, j, d) { ... }, where i_plot will be the index of the plot on the page (necessary to call various helper functions), (i, j) is the index of the point in the grid, and d is an object that contains the input_data that was sent in the form of data when making the plot.

show_mesh

TypeBoolean.
Defaulttrue
NotesShows the mesh.

show_surface

TypeBoolean.
Defaulttrue
NotesShows the surface.

uniform_mesh_color

TypeBoolean.
Defaulttrue
NotesSays whether to use the constant colour for the mesh, as given by mesh_color. If false, then the mesh will be coloured identically to the surface.

Functions

All functions in the three_d.js code are exported, so if you want to study the source code and call specific functions, you're able to do so. The following is a list of some of the more potentially useful ones, starting with those that are common to both scatterplots and surfaces.


three_d.destroy_plot(i_plot)

Destroys plot i_plot.


three_d.get_current_camera(i_plot)

Returns the currently active camera object (either the perspective or orthographic camera) of plot i_plot.


three_d.get_i_plot(div_id)

Returns the i_plot value of the plot created in the <div> element with id equal to div_id. Shouldn't be necessary unless you're destroying and creating plots.


three_d.update_render(i_plot)

Updates the rendering of plot i_plot, often necessary after changing some details in the plot.


Functions for scatterplots

three_d.change_data(i_plot, params[, new_dataset, animate, append])

Updates plot i_plot based on the data in the params object. The last three arguments are optional booleans. If new_dataset is true, then most of the plot will be destroyed and rebuilt from scratch. If the params.data array contains a different number of data points than the existing plot, then new_dataset will be se to true. If new_dataset is false, then by default animate is true, and the plot will smoothly transition the data points to their new locations. If animate is set to false, then the points will immediately jump there. If append is set to true, then the points will be added to the dataset and appear without animation.

The params object can set axes like for three_d.make_scatter(), but it can also optionally set params.keep_axes to true, which will leave the axes unchanged. If not appending data, and if there is at least one date/time axis, then the time_axis property is compulsory.


three_d.hide_label(i_plot, i)

Hides the label of point i in plot i_plot.


three_d.hide_point(i_plot, i[, hide_segments])

Hides point i in plot i_plot. The optional arugment show_segments is by default true if points are connected; if true, then it will also hide the lines going to or from the point.


three_d.hide_point_segments(i_plot, i)

Hides the lines going to or from point i in plot i_plot.


three_d.make_scatter(params)

Makes a scatter plot based on the information in the params object.


three_d.set_label_background_color(i_plot, i, col)

Sets the background colour of the label of point i in plot i_plot to numeric value col.


three_d.set_label_color(i_plot, i, col)

Sets the colour of the text in the label of point i in plot i_plot to numeric value col.


three_d.set_point_color(i_plot, i, col[, set_segments])

Sets the colour of point i in plot i_plot to numeric value col. The optional boolean set_segments is by default true and will also change the colour of any lines coming to or from the point.


three_d.set_point_position(i_plot, i, position[, set_segments, world_space])

Sets the position of point i in plot i_plot to the (x, y, z)-values defined in position. The optional boolean argument set_segments is by default true and will update the end-point of lines coming to or from the point. The optional boolean argument world_space will if true mean that position is interpreted in world space, where the longest axis runs from -1 to +1.


three_d.set_point_segments_color(i_plot, i, col)

Sets the colour of the end points of the lines going to or from point i in plot i_plot to numeric value col.


three_d.set_point_segments_position(i_plot, i, position[, world_space, is_null])

Sets the position of the end points of the lines going to or from point i of plot i_plot to the (x, y, z)-values defined in position. The optional boolean argument world_space will if true mean that position is interpreted in world space, where the longest axis runs from -1 to +1. The optional boolean is_null will make the segments null, regardless of whether or not position has any null entries (this is a strange argument, and it comes from me writing myself into a little hole and finding this way to get myself out easily).


three_d.set_point_size(i_plot, i, size[, scale_factor])

Sets the size of point i in plot i_plot to size pixels. The optional argument scale_factor is usually unnecessary but if you are changing a large number of sizes, then it might be more efficient to pre-calculate scale_factor = 2 * three_d.get_scale_factor(i_plot); and pass that argument.


three_d.show_label(i_plot, i)

Shows the label of point i in plot i_plot.


three_d.show_point(i_plot, i[, show_segments])

Shows point i in plot i_plot. The optional arugment show_segments is by default true if points are connected; if true, then it will also show the lines going to or from the point.


three_d.show_point_segments(i_plot, i)

Shows the lines going to or from point i in plot i_plot.


Functions for surfaces

three_d.change_data(i_plot, params[, new_dataset, animate, append])

Updates plot i_plot based on the data in the params object. The last three arguments are optional booleans. If new_dataset is true, then most of the plot will be destroyed and rebuilt from scratch. If params.data.z is of different dimensions to the existing plot, then new_dataset will be se to true. If new_dataset is false, then by default animate is true, and the plot will smoothly transition the grid nodes to their new locations. If animate is set to false, then the points will immediately jump there. If append is set to true, then the grid will be extended and appear without animation; in the latter case, the params object must have an append_axis property, to define which direction to append to: choices are "+x", "-x", "+y", "-y".

The params object can set axes like for three_d.make_scatter(), but it can also optionally set params.keep_axes to true, which will leave the axes unchanged. If not appending data, and if there is at least one date/time axis, then the time_axis property is compulsory.


three_d.hide_mesh(i_plot)

Hides the mesh in plot i_plot.


three_d.hide_mesh_point(i_plot, i, j)

Hides point (i, j) from the mesh in plot i_plot.


three_d.hide_mesh_x(i_plot)

Hides the mesh lines in the x-direction in plot i_plot.


three_d.hide_mesh_y(i_plot)

Hides the mesh lines in the y-direction in plot i_plot.


three_d.hide_surface(i_plot)

Hides the surface in plot i_plot.


three_d.hide_surface_point(i_plot, i, j)

Hides point (i, j) from the surface in plot i_plot.


three_d.make_surface(params)

Makes a surface/mesh plot based on the information in params.


three_d.set_mesh_point_color(i_plot, i, j, col)

Sets the colour of point (i, j) from the mesh in plot i_plot.


three_d.set_mesh_uniform_color(i_plot, col)

If col is numeric, then sets the colour of from the mesh in plot i_plot to col. If col == "variable", then sets the mesh to have the same colours as the surface.


three_d.set_surface_color_scale(i_plot, color_scale)

Sets the z-based colour scale to the color_scale; as in the object passed to three_d.make_surface, this can be a string out of "inferno", "magma", "plasma", "viridis", and "grayscale" (or "greyscale"), or it can be a function that takes one argument (assumed 0-1) and returns an array of three numbers, each between 0 and 1, representing red, green, and blue channels.


three_d.set_surface_point_color(i_plot, i, j, col[, permanent])

Sets the colour of point (i, j) from the surface in plot i_plot to numeric value col. The optional argument permanent is by default false; if true, then the surrounding colours will be fully interpolated, the mesh colour will also be updated, as will input_data.color in the three_d.plots[i_plot].mesh_points[i][j].


three_d.set_surface_point_z(i_plot, i, j, z)

Changes the z-value of point (i, j) in both the surface and mesh of plot i_plot to z. Unlike with colours or show/hide, the z-values of surface and mesh points are always linked. (Unless you change their properties directly, rather than with one of these functions.)


three_d.show_mesh(i_plot)

Shows the mesh in plot i_plot.


three_d.show_mesh_point(i_plot, i, j)

Shows point (i, j) from the mesh in plot i_plot.


three_d.show_mesh_x(i_plot)

Shows the mesh lines in the x-direction in plot i_plot.


three_d.show_mesh_y(i_plot)

Shows the mesh lines in the y-direction in plot i_plot.


three_d.show_surface(i_plot)

Shows the surface in plot i_plot.


three_d.show_surface_point(i_plot, i, j)

Shows point (i, j) from the surface in plot i_plot.


three_d.use_uniform_mesh_color(i_plot)

Sets the colour of the mesh in plot i_plot to its current uniform colour.

Posted 2016-10-02, updated 2016-12-22 (version 1).


Home > three_d.js