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>
|
19 | See more <a href="https://bl.ocks.org/niekes" target="_blank">examples</a>.
|
20 |
|
21 | ## Installing
|
22 |
|
23 | If 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 |
|
33 | For a specific version:
|
34 | ```html
|
35 | <script src="https://unpkg.com/d3-3d@version/build/d3-3d.js"></script>
|
36 | ```
|
37 |
|
38 | ## Import
|
39 |
|
40 | ES6:
|
41 |
|
42 | ```js
|
43 | import { _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 |
|
64 | With **d3-3d** you can easily visualize your 3d data.
|
65 | ```js
|
66 | var data3D = [ [[0,-1,0],[-1,1,0],[1,1,0]] ];
|
67 |
|
68 | var triangles3D = d3._3d()
|
69 | .scale(100)
|
70 | .origin([480, 250])
|
71 | .shape('TRIANGLE');
|
72 |
|
73 | var projectedData = triangles3D(data3D);
|
74 |
|
75 | init(projectedData);
|
76 |
|
77 | function 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 |
|
87 | Constructs a new function object with the default settings.
|
88 |
|
89 | ### Shapes
|
90 | Depending 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 |
|
107 | Sets the shape to *shape*. If *shape* is not specified the current shape will be returned.
|
108 |
|
109 | If *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
|
112 | var 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 |
|
117 | If *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
|
120 | function x(p) {
|
121 | return p[0];
|
122 | }
|
123 | ```
|
124 | This 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 |
|
128 | If *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
|
131 | function y(p) {
|
132 | return p[1];
|
133 | }
|
134 | ```
|
135 | This 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 |
|
139 | If *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
|
142 | function z(p) {
|
143 | return p[2];
|
144 | }
|
145 | ```
|
146 | This 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 |
|
152 | If *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 |
|
158 | If *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 |
|
164 | If *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 |
|
170 | If *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 |
|
176 | If *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 |
|
180 | Sorts 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 |
|
184 | Constructs 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>
|