UNPKG

9.84 kBMarkdownView Raw
1# d3-3d
2**d3-3d** is meant for 3d visualizations. **d3-3d** allows the projection of 3d data onto the screen in the webbrowser. It is specially designed to work with **[d3.js](https://d3js.org/)**.
3
4[![Codecov](https://img.shields.io/codecov/c/github/niekes/d3-3d)](https://app.codecov.io/gh/niekes/d3-3d)
5[![Travis (.org) branch](https://travis-ci.com/Niekes/d3-3d.svg?branch=master)](https://travis-ci.com/github/Niekes/d3-3d)
6[![npm](https://img.shields.io/npm/dt/d3-3d)](https://www.npmjs.com/package/d3-3d)
7[![npm](https://img.shields.io/npm/dw/d3-3d)](https://www.npmjs.com/package/d3-3d)
8[![npm](https://img.shields.io/npm/l/d3-3d)](https://github.com/Niekes/d3-3d/blob/master/LICENSE)
9[![npm bundle size](https://img.shields.io/bundlephobia/minzip/d3-3d)](https://bundlephobia.com/result?p=d3-3d)
10[![npm](https://img.shields.io/npm/v/d3-3d)](https://www.npmjs.com/package/d3-3d)
11
12<table>
13 <tr>
14 <td> <a target="_blank" href="https://bl.ocks.org/niekes/e920c03edd7950578b8a6cded8b5a1a5"> <img src="assets/surfaceplot.gif"> </a> </td>
15 <td> <a target="_blank" href="https://bl.ocks.org/niekes/1c15016ae5b5f11508f92852057136b5"> <img src="assets/3d-scatterplot.gif"> </a> </td>
16 <td> <a target="_blank" href="https://bl.ocks.org/niekes/613d43d39372f99ae2dcea14f0f90617"> <img src="assets/3d-barchart.gif"> </a> </td>
17 </tr>
18</table>
19See more <a href="https://bl.ocks.org/niekes" target="_blank">examples</a>.
20
21## Installing
22
23If you use npm, `npm install d3-3d`. You can also download the [latest release](https://github.com/Niekes/d3-3d/releases). Otherwise use [unpkg](https://unpkg.com/d3-3d/) to get the latest release. For example:
24
25```html
26<script src="https://unpkg.com/d3-3d/build/d3-3d.js"></script>
27
28<!-- OR -->
29
30<script src="https://unpkg.com/d3-3d/build/d3-3d.min.js"></script>
31```
32
33For a specific version:
34```html
35<script src="https://unpkg.com/d3-3d@version/build/d3-3d.js"></script>
36```
37
38## Import
39
40ES6:
41
42```js
43import { _3d } from 'd3-3d' ;
44```
45
46## API Reference
47
48* [d3._3d](#_3d) - create a new 3d function object.
49* [*_3d*.shape](#shape) - set the shape.
50* [*_3d*.x](#x) - set the x accessor.
51* [*_3d*.y](#y) - set the y accessor.
52* [*_3d*.z](#z) - set the z accessor.
53* [*_3d*.scale](#scale) - sets the scale for the projected points.
54* [*_3d*.rotateX](#rotateX) - set the angle for the x rotation.
55* [*_3d*.rotateY](#rotateY) - set the angle for the y rotation.
56* [*_3d*.rotateZ](#rotateZ) - set the angle for the z rotation.
57* [*_3d*.rotateCenter](#rotateCenter) - set the the rotation center.
58* [*_3d*.sort](#sort) - sort the 3d elements by the centroid.
59* [*_3d*.draw](#draw) - draw the 3d elements.
60
61### Overview
62**d3-3d** uses the [browser's coordinate system](https://www.w3.org/TR/css-transforms-1/#transform-rendering) and [orthographic projection](https://en.wikipedia.org/wiki/Orthographic_projection) to display your data on the screen. It will calculate the centroid for all elements and the orientation for your polygons. Due to the fact that SVG isn't very 3d compatible **d3-3d** adds 3d transformations to SVG.
63
64With **d3-3d** you can easily visualize your 3d data.
65```js
66var data3D = [ [[0,-1,0],[-1,1,0],[1,1,0]] ];
67
68var triangles3D = d3._3d()
69 .scale(100)
70 .origin([480, 250])
71 .shape('TRIANGLE');
72
73var projectedData = triangles3D(data3D);
74
75init(projectedData);
76
77function init(data){
78
79 var triangles = svg.selectAll('path').data(data);
80
81 // add your logic here...
82
83}
84```
85<a name="_3d" href="#_3d">#</a> d3.<b>_3d</b>() [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L58 "Source")
86
87Constructs a new function object with the default settings.
88
89### Shapes
90Depending on the shape the input data array has to be accordingly to the shape.
91* **POINT** A point is represented by the `<circle>` element. It does not have a draw function because it can be represented as a `<circle>`. The input data array has to be an array of points where each point has three coordinates which can be accessed via the [x](#x), [y](#y) and [z](#z) accessors.
92* **LINE** A line is represented by the `<line>` element. It does not have a draw function because it can be represented as a `<line>`. The input data array has to be an array of lines where each line is defined by a start- and an endpoint.
93* **LINE_STRIP** A continuous line is represented by the `<path>` element. The input data array has to be an array of points. Every point will be connected to the next point in the input data array.
94* **TRIANGLE** A triangle represented by the `<path>` element. The input data array has to be an array of triangles where each triangle is defined by three points in counter-clockwise order.
95* **PLANE** A plane is represented by the `<path>` element. The input data array has to be an array of planes where each plane is defined by four points in counter-clockwise order.
96* **GRID** A grid is represented by x planes. The input data array has to be an array of points. The [shape](#shape) function aspects the amount of points per row as a second argument. **d3-3d** will construct planes out of the passed data.
97_NOTE:_ A grid has to have always the same number of points per row. Otherwise the code will break.
98* **SURFACE** equivalent to `GRID`
99* **CUBE** A grid is represented by 4 planes. The input data array has to be an array of cubes where each cube is defined by 8 vertices. To get the orientation and centroid calculation right you should pass in the data like so:
100
101![cube](assets/cube.png "Cube")
102
103<a name="shape" href="#shape">#</a> _3d.<b>shape</b>(shape) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L87 "Source")
104
105_Default:_ `'POINT'`
106
107Sets the shape to *shape*. If *shape* is not specified the current shape will be returned.
108
109If *shape* is specified, sets the shape to the specified shape and returns the **d3-3d** function object. If *shape* is not specified, returns the current shape.
110
111```js
112var triangles3D = d3._3d().shape('TRIANGLE');
113```
114
115<a name="x" href="#x">#</a> _3d.<b>x</b>([x]) [<>](https://github.com/Niekes/d3-3d/blob/master/src/point.js#L1 "Source")
116
117If *x* is specified, sets the x accessor to the specified function or number and returns the **d3-3d** function object. If *x* is not specified, returns the current x accessor, which defaults to:
118
119```js
120function x(p) {
121 return p[0];
122}
123```
124This function will be invoked for each point in the input data array.
125
126<a name="y" href="#y">#</a> _3d.<b>y</b>([y]) [<>](https://github.com/Niekes/d3-3d/blob/master/src/point.js#L5 "Source")
127
128If *y* is specified, sets the y accessor to the specified function or number and returns the **d3-3d** function object. If *y* is not specified, returns the current y accessor, which defaults to:
129
130```js
131function y(p) {
132 return p[1];
133}
134```
135This function will be invoked for each point in the input data array.
136
137<a name="z" href="#z">#</a> _3d.<b>z</b>([z]) [<>](https://github.com/Niekes/d3-3d/blob/master/src/point.js#L9 "Source")
138
139If *z* is specified, sets the z accessor to the specified function or number and returns the **d3-3d** function object. If *z* is not specified, returns the current z accessor, which defaults to:
140
141```js
142function z(p) {
143 return p[2];
144}
145```
146This function will be invoked for each point in the input data array.
147
148<a name="scale" href="#scale">#</a> _3d.<b>scale</b>(scale) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L71 "Source")
149
150_Default:_ `1`
151
152If *scale* is specified, sets the scale to the specified number and returns the **d3-3d** function object. If *scale* is not specified, returns the current scale.
153
154<a name="rotateX" href="#rotateX">#</a> _3d.<b>rotateX</b>(angle) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L75 "Source")
155
156_Default:_ `0`
157
158If *angle* is specified, sets rotateX to the specified number and returns the **d3-3d** function object. If *angle* is not specified, returns the current angle.
159
160<a name="rotateY" href="#rotateY">#</a> _3d.<b>rotateY</b>(angle) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L79 "Source")
161
162_Default:_ `0`
163
164If *angle* is specified, sets rotateY to the specified number and returns the **d3-3d** function object. If *angle* is not specified, returns the current angle.
165
166<a name="rotateZ" href="#rotateZ">#</a> _3d.<b>rotateZ</b>(angle) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L83 "Source")
167
168_Default:_ `0`
169
170If *angle* is specified, sets rotateZ to the specified number and returns the **d3-3d** function object. If *angle* is not specified, returns the current angle.
171
172<a name="rotateCenter" href="#rotateCenter">#</a> _3d.<b>rotateCenter</b>(point) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#L87 "Source")
173
174_Default:_ `[0, 0, 0]`
175
176If *point* is specified, sets rotateCenter to the specified point and returns the **d3-3d** function object. If *rotateCenter* is not specified, returns the current rotateCenter.
177
178<a name="sort" href="#sort">#</a> _3d.<b>sort</b>(a,b) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#107 "Source")
179
180Sorts the elements accordingly to the z coordinate of the calculated centroid.
181
182<a name="draw" href="#draw">#</a> _3d.<b>draw</b>(shape) [<>](https://github.com/Niekes/d3-3d/blob/master/src/3d.js#107 "Source")
183
184Constructs a string for the SVG `<path>` element. Depending on the [shape](#shape) this function will take care how the elements get drawn. For instance, if you choose `'TRIANGLE'` **d3-3d** aspects that you want to draw a triangle with three points and each point has three coordinates. The [*_3d*.draw](#draw) method will draw a triangle with these three points. If you want to draw a plane, you have to pass in four points and so on.
185
186# Funding
187<a href="https://www.buymeacoffee.com/niekes" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="70"></a>