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.
three_d.make_scatter()div_id| Type | String. |
| Default | None; must be specified. |
| Notes | Compulsory. It is the id of the <div> element that will contain the plot. |
data| Type | Array of objects, one object per data point. |
| Default | None; must be specified. |
| Notes | Compulsory. 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| Type | Either a CSS string or numeric colour. |
| Default | 0xFFFFFF. |
| Notes | The colour of the edges of the box. |
axis_font_color| Type | CSS string or numeric colour. |
| Default | "#FFFFFF". |
| Notes | Colour of the axis titles. |
axis_font_size| Type | Number (in pixels). |
| Default | 30. |
| Notes | Font size for the axis titles. |
axis_tick_gaps| Type | Array of three numbers. |
| Default | [0.1, 0.1, 0.1]. |
| Notes | The 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| Type | Array of three numbers. |
| Default | [0.3, 0.3, 0.3]. |
| Notes | Distance 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| Type | Array of three strings. |
| Default | ["x", "y", "z"]. |
| Notes | Titles for the x-, y-, and z-axes. |
background_color| Type | CSS string or numeric colour. |
| Default | "#000000". |
| Notes | Background colour of the plot. |
camera_r| Type | Number. |
| Default | 5. |
| Notes | Radius 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| Type | Function. |
| Default | None. |
| Notes | The 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| Type | String. |
| Default | None. |
| Notes | If 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| Type | Either a CSS colour string or a numeric colour. |
| Default | 0xFFFFFF. |
| Notes | The colour of the points, if not specified by the color property in its data point object. |
default_point_height| Type | Number (in pixels). |
| Default | 20. |
| Notes | Used in the absence of a size property in the data point object. |
dynamic_axis_labels| Type | Boolean. |
| Default | false. |
| Notes | Says 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| Type | String. |
| Default | None. |
| Notes | An 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| Type | String. |
| Default | "Arial, sans-serif". |
| Notes | The font to use for all text in the plot. |
fov| Type | Number. |
| Default | 47.25. |
| Notes | Initial field of view for the perspective camera in degrees. |
geom_type| Type | String. |
| Default | "quad". |
| Notes | Either "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| Type | A CSS string or numeric colour. |
| Default | 0x808080. |
| Notes | Colour of the grid lines. |
height| Type | Number (in pixels). |
| Default | Calculated so that the plot is the largest square that fits in the parent <div> element. |
| Notes |
hidden_margins| Type | Boolean. |
| Default | false. |
| Notes | If 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| Type | Array of three numbers. |
| Default | [0, 0, 0]. |
| Notes | The 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| Type | Number. |
| Default | 0. |
| Notes | The rotation (in radians) applied to the camera after it is in the position defined by init_lonlat, i.e., the
roll. |
init_lonlat| Type | Array of two numbers. |
| Default | [-three_d.tau/8, three_d.tau/8]. |
| Notes | The 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| Type | Number (in pixels). |
| Default | 16. |
| Notes | Font size for the labels attached to the data points. |
max_fov| Type | Number. |
| Default | 90. |
| Notes | The 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| Type | Number. |
| Default | Half the camera_r value. |
| Notes | This sets a limit on how far you can pan. |
max_point_height| Type | Number (in pixels). |
| Default | 25. |
| Notes | Not 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| Type | Number. |
| Default | 1. |
| Notes | The 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| Type | Function. |
| Default | None. |
| Notes | The 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| Type | Function. |
| Default | None. |
| Notes | The 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| Type | Number. |
| Default | 1. |
| Notes | If 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| Type | Array of three integers. |
| Default | [4, 4, 4]. |
| Notes | The (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| Type | Number. |
| Default | Calculated to be equivalent to the perspective fov. |
| Notes | An 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| Type | Number. |
| Default | Set based on the aspect ratio of the plot and ortho_top if the latter is specifed; set based on the
perspective fov if not. |
| Notes | An 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| Type | String. |
| Default | "sphere". |
| Notes | The 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| Type | Array of three booleans. |
| Default | [false, false, false]. |
| Notes | The 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| Type | Boolean. |
| Default | true. |
| Notes | Says whether or not to show the axis titles (may still be switched on or off from the toggle). |
show_box| Type | Boolean. |
| Default | true. |
| Notes | Says whether or not to show the axes box (may still be switched on or off from the control toggle). |
show_grid| Type | Boolean. |
| Default | true |
| Notes | Says whether or not to show the grid lines (may still be switched on or off from the control toggle). |
show_labels| Type | Boolean. |
| Default | true. |
| Notes | Says 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| Type | Boolean. |
| Default | true. |
| Notes | Says whether or not to show the snap options ("Reset" and the snap to axis). |
show_ticks| Type | Boolean. |
| Default | true. |
| Notes | Says whether or not to show the axis ticks (may still be switched on or off from the control toggle). |
show_toggles| Type | Boolean. |
| Default | true. |
| Notes | Says whether or not to show the control toggles. |
size_exponent| Type | Number. |
| Default | 2. |
| Notes | Defines 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| Type | Number. |
| Default | The maximum size value of the data point objects. |
| Notes | The 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| Type | CSS string or numeric colour. |
| Default | "#FFFFFF". |
| Notes | Colour of the tick values. |
tick_font_size| Type | Number (in pixels). |
| Default | 28. |
| Notes | Font size for the tick values. |
tick_formats| Type | Array of three strings. |
| Default | ["", "", ""]. |
| Notes | Format 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| Type | Array of three numbers. |
| Default | [0.03, 0.03, 0.03]. |
| Notes | The 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| Type | String. |
| Default | "perspective". |
| Notes | Either "perspective" or "orthographic". |
width| Type | Number (in pixels). |
| Default | Calculated so that the plot is the largest square that fits in the parent <div> element. |
| Notes |
x_scale_bounds| Type | Array of two numbers. |
| Default | Calculated from the range of the data, extended by 10% on each side. |
| Notes | Defines 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| Type | Array of numbers. |
| Default | Calculated by d3. |
| Notes | This will manually set tick values for the x-axis. |
y_scale_bounds| Type | Array of two numbers. |
| Default | Calculated from the range of the data, extended by 10% on each side. |
| Notes | Defines 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| Type | Array of numbers. |
| Default | Calculated by d3. |
| Notes | This will manually set tick values for the y-axis. |
z_scale_bounds| Type | Array of two numbers. |
| Default | Calculated from the range of the data, extended by 10% on each side. |
| Notes | Defines 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| Type | Array of numbers. |
| Default | Calculated by d3. |
| Notes | This will manually set tick values for the z-axis. |
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.