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.

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), 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.

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_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).

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.

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.

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.

geom_type

TypeString.
Default"quad".
NotesEither "quad" or "point". 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).

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

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.

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.

label_font_size

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

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.

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.

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.

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.

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.

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.)

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", "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.

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_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.

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.

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.

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, 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).

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.

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.

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

Updates plot i_plot based on the data in the params object. The last two arguments are both 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.


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.hide_label(i_plot, i)

Hides the label of point i in plot i_plot.


three_d.hide_point(i_plot, i)

Hides 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_color(i_plot, i, col)

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


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_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)

Shows point i in plot i_plot.


three_d.update_render(i_plot)

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

Posted 2016-10-02.


Home > three_d.js