31:T499,md`## Illustration key The illustration above is a cutaway side-view of the three.js camera and scene. The horizontal view represents the z axis and the vertical is the y. The black dot represents the camera. The green line shows the height and poistion of the group of dots. The dots are centered around the position \`x: 0, y: 0, z: 0\`. The dotted line is the z position you adjusted above -- the distance between the camera and the points in the z-axis. The purple lines show the field of view angle. What they contain determines what is visible in the visualization. The blue line represents the height of the visualization itself, which is useful for thinking about scale. The dark gray rectangle represents the space between the near and far plane. Anything outside of that space will not be rendered. Note that the planes are defined relative to the position of the camera.`32:T65e,md`## What is going on? There's lots of theoretical background for how this stuff interacts but for here I just want to list some practical observations: - If your goal is to see all the dots at once you can either move the camera further away or widen the field of view. - The closer the camera gets to the dots the bigger the dots get. - If you move the camera close and widen the frame of view so you can see them all, the individual dots will be a large size. If you move the camera really far back and narrow the field of view so the group of dots fill the screen, the individual dots will be small. - I often have an idea of the size each individual dot should be when I'm zoomed out to see all of them. To dial that size in you could move the camera in and out until you find the right individual dot size, than adjust the field of view so that all the dots are visible. In this way changing field of view lets you adjust how tightly the dots are packed together. - Keep in mind that adjusting the field of view also adjusts how fast the zoom feels when you're moving the camera. With a wide field of view it won't take much camera movement to go from all the dots being visible to being very close. What you want to do there depends on how you want the zoom to feel. - The near and far plane aren't really important when doing this type of 2D visualization. They're more useful for managing performance when you've got lots of 3D objects. Still it's worth knowing how they work just to make sure your points are always contained within them -- otherwise your points won't show up at all and it can be difficult to debug.`33:T76e,function drawCamera(ctx) { let cx = width/2; let cy = canvas_height/2; let scaled_z = camera_z * canvas_scale; let y_adjust = -camera_y * canvas_scale; let z_padding = canvas_z_padding * canvas_scale; // Near and far threshold ctx.beginPath(); ctx.moveTo(width - z_padding - scaled_z + near_plane * canvas_scale, 0) ctx.lineTo(width - z_padding - scaled_z + far_plane * canvas_scale, 0) ctx.lineTo(width - z_padding - scaled_z + far_plane * canvas_scale, canvas_height) ctx.lineTo(width - z_padding - scaled_z + near_plane * canvas_scale, canvas_height) ctx.closePath(); ctx.fillStyle = "#ddd"; ctx.fill(); // Z line ctx.beginPath(); ctx.moveTo(width - z_padding, cy + y_adjust) ctx.lineTo(width - z_padding - scaled_z, cy + y_adjust); ctx.setLineDash([4, 4]); ctx.lineWidth = 2; ctx.stroke(); // Field of view triangle ctx.setLineDash([]); ctx.beginPath(); ctx.moveTo(width - z_padding - scaled_z, cy + y_adjust) ctx.lineTo(width - z_padding, cy - (fov_height / 2 * canvas_scale) + y_adjust); ctx.lineTo(width - z_padding, cy + (fov_height / 2 * canvas_scale) + y_adjust); ctx.closePath(); ctx.strokeStyle = "purple"; ctx.lineWidth = 3; ctx.stroke(); // Camera circle ctx.beginPath(); ctx.arc(width - z_padding - scaled_z, cy + y_adjust, 9, 0, Math.PI * 2, true); ctx.lineWidth = 0; ctx.fillStyle = "black"; ctx.fill(); // Screen indicator ctx.beginPath(); ctx.moveTo(width - z_padding, cy - viz_height / 2 * canvas_scale); ctx.lineTo(width - z_padding, cy + viz_height / 2 * canvas_scale); ctx.lineWidth = 4; ctx.strokeStyle = "blue"; ctx.stroke(); // Dots indicator ctx.beginPath(); ctx.moveTo(width - z_padding, cy - points_radius * canvas_scale); ctx.lineTo(width - z_padding, cy + points_radius * canvas_scale); ctx.lineWidth = 6; ctx.strokeStyle = "green"; ctx.stroke(); }34:[] 2f:{"title":"Understanding scale and the three.js perspective camera","cells":[{"id":0,"value":"md`# Understanding scale and the three.js perspective camera\n\nI recently used three.js for a 2D data visualization project. I chose three.js because it was able to smoothly render more points (over 50,000 in this case) than SVG or canvas. The project turned out well, but it had its challenges. One of the biggest was figuring out how to get a Google maps style (you could also say [d3-style](https://bl.ocks.org/mbostock/4e3925cdc804db257a86fdef3a032a45)) zoom and pan working, and the key for that turned out to be getting my head around how the three.js camera works.\n\nThis notebook looks at how the three.js camera interacts with the objects in a scene, and how you can think about that in terms of scale. It's focused on using it for 2D data visualization, but you can extend the concepts to 3D work as well (especially if you combine it with this similar [three.js example](https://threejs.org/examples/#webgl_camera)).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":375,"value":"md`## The visualization and the camera\n\nThe meat of this notebook is below. It is a three.js visualization of some points and an illustration showing a cutaway side view of the position of the points and camera in that visualization. Between them are three sliders. One adjusts the field-of-view (fov) angle for the camera, the other two adjust the z and y position of the camera. There's an explanation of what all that means after, but I wanted to put the visualization and the illustration close together so you can see how each are affected by the changes.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":762,"value":"md`Field of view angle: __${fov} degrees__. Camera z-position: __${camera_z}__. Camera y-position: __${camera_y}__.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":493,"value":"{\n const renderer = new THREE.WebGLRenderer({antialias: true});\n renderer.setSize(width, viz_height);\n renderer.setPixelRatio(devicePixelRatio);\n try {\n while(true) {\n renderer.render(scene, camera);\n yield renderer.domElement;\n }\n } finally {\n renderer.dispose();\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":49,"value":"viewof fov = DOM.range(1, 140, 1)","pinned":false,"hidden":false,"mode":"ojs"},{"id":80,"value":"viewof camera_z = DOM.range(1, 500, 10)","pinned":false,"hidden":false,"mode":"ojs"},{"id":695,"value":"viewof camera_y = DOM.range(-100, 100, 1)","pinned":false,"hidden":false,"mode":"ojs"},{"id":141,"value":"{\n const ctx = DOM.context2d(width, canvas_height);\n const canvas = ctx.canvas;\n canvas.style.background = \"#efefef\";\n drawCamera(ctx);\n return canvas\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":812,"value":"md`Near plane: __${near_plane}__. Far plane: __${far_plane}__.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":723,"value":"viewof near_plane = DOM.range(1, 20, 1)","pinned":false,"hidden":false,"mode":"ojs"},{"id":726,"value":"viewof far_plane = DOM.range(20, 800, 10)","pinned":false,"hidden":false,"mode":"ojs"},{"id":918,"value":"md`Point settings:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":915,"value":"viewof point_size = DOM.range(2, 16, 1)","pinned":false,"hidden":false,"mode":"ojs"},{"id":923,"value":"viewof sizeAttenuation = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":390,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":755,"value":"md`## Using these settings in three.js\n\nField of view, near plane and far plane are all set when you create the three.js camera. You also set aspect ratio, which you should set to the visualization width divided by height unless you want to do something weird.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":765,"value":"camera = {\n // Initial camera set-up\n let aspect_ratio = width / viz_height;\n let camera = new THREE.PerspectiveCamera(fov, aspect_ratio, near_plane, far_plane);\n \n // Setting the camera position. These are the values you'll update to pan and zoom based on mouse input.\n camera.position.set(0, camera_y, camera_z );\n return camera;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":783,"value":"md`You also set an initial camera position. Adjusting the camera position is how you create a pan and zoom effect.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":447,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":457,"value":"md`## About point settings\n\nBesides changing the field of view and camera position, you can also control the size of the points by directly setting their size. In a real project you probably want to set the field of view to something constant (20 and 45 degrees seem popular) and dial in the point size by adjusting the actual point size setting.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":795,"value":"md`Another setting to add to the mix is the \\`sizeAttenuation\\` setting on the point material. Size attenuation means the points change size as you zoom in and out. Turning it off means they remain the same size at all zoom levels. I actually think turning it off works really well for data visualizations. Since the points stay the same size the effect is that the space between them increases as you zoom in, this means that a cluster of overlapping points when your zoomed out gets spread apart as you zoom in, so that you can see the relationship between all the points.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":798,"value":"md`If you turn off size attenuation then the field of view no longer has an effect on the size of the points (because they're always the same size). That means the only difference the field of view setting makes is how much distance the camera needs to travel to zoom into the points. Both point size and size attenuation are set on the points material object of the point.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":801,"value":"pointsMaterial = new THREE.PointsMaterial({\n size: point_size,\n sizeAttenuation: sizeAttenuation,\n vertexColors: THREE.VertexColors,\n map: circle_sprite,\n transparent: true\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":820,"value":"md`## How to think about scale\n\nMy main interest in understanding the camera was in setting up a good zoom. Specifically I wanted to plug [d3-zoom](https://github.com/d3/d3-zoom) into my three.js visualization. Rather than a camera position, d3-zoom uses the concept of scale: the visualization scales up from 1 as you zoom in. To use d3 zoom I needed to map its scale value into a three.js camera position. The key turned out to be trigonometry, which you can use to calculate height of the field of view based on the camera position. I first saw the calculation in the [three.map.control plugin](https://github.com/anvaka/three.map.control), there's more discussion of the concept [on stack overflow](https://stackoverflow.com/questions/13350875/three-js-width-of-view/13351534#13351534).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":834,"value":"fov_height = {\n let half_fov = fov/2;\n let half_fov_radians = toRadians(half_fov);\n let half_fov_height = Math.tan(half_fov_radians) * camera_z;\n return half_fov_height * 2;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":841,"value":"md`You first divide the field of view by two, so you can work with the right angle formed by the purple and dotted lines. You convert that angle to radians, and then you find the tangent of that angle and multiple by the camera's z position (it is the TOA part of SOHCAHTOA). You multiple that by two to find the height of the field of view at the scene's z position 0 (where the points are).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":845,"value":"mutable scale = viz_height / fov_height","pinned":true,"hidden":false,"mode":"ojs"},{"id":849,"value":"md`You divide the field of view height by the height of the visualization to find the scale. A scale of 1 means that the position of the points in visualization match their coordinates. So a point at coordinate (10, 10) is 10px to right of the center and 10px towards the top (in three.js the center is point (0, 0)). Having the scale value makes it possible to plug in d3-zoom. It can also let you do nice things like calculate what z position the camera needs to have to show all the points.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":884,"value":"md`## Wrapping up\n\nHopefully this helps you understand how the three.js camera works. It certainly helped me to write it. Let me know if you have any questions or if I got anything wrong: @GrantCuster on twitter or grantcuster at gmail.com. I'm hoping to have another, broader notebook on using three.js for 2D data visualization up soon.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":862,"value":"md`### Illustration code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":292,"value":"canvas_z_fit = 1000","pinned":false,"hidden":false,"mode":"ojs"},{"id":294,"value":"canvas_z_padding = 40","pinned":false,"hidden":false,"mode":"ojs"},{"id":301,"value":"canvas_scale = width/(canvas_z_fit + canvas_z_padding * 2)\n","pinned":false,"hidden":false,"mode":"ojs"},{"id":855,"value":"mutable canvas_height = 400 * canvas_scale","pinned":false,"hidden":false,"mode":"ojs"},{"id":34,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":873,"value":"md`### Visualization code`","pinned":false,"hidden":false,"mode":"ojs"},{"id":877,"value":"viz_height = 350","pinned":false,"hidden":false,"mode":"ojs"},{"id":880,"value":"points_radius = 100","pinned":false,"hidden":false,"mode":"ojs"},{"id":6,"value":"scene = {\n const scene = new THREE.Scene();\n scene.background = new THREE.Color(0xefefef);\n scene.add(points);\n return scene;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":127,"value":"points = {\n let pointsGeometry = new THREE.Geometry();\n \n let colors = [];\n for (let datum of generated_points) {\n let vertex = new THREE.Vector3(datum.position[0], datum.position[1], 0);\n pointsGeometry.vertices.push(vertex);\n let color = new THREE.Color(color_array[datum.group]);\n colors.push(color);\n }\n pointsGeometry.colors = colors;\n return new THREE.Points(pointsGeometry, pointsMaterial);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":133,"value":"circle_sprite= new THREE.TextureLoader().load(\n \"https://blog.fastforwardlabs.com/images/2018/02/circle-1518727951930.png\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":130,"value":"color_array = [\n \"#1f78b4\",\n \"#b2df8a\",\n \"#33a02c\",\n \"#fb9a99\",\n \"#e31a1c\",\n \"#fdbf6f\",\n \"#ff7f00\",\n \"#6a3d9a\",\n \"#cab2d6\",\n \"#ffff99\"\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":125,"value":"point_num = 1000","pinned":false,"hidden":false,"mode":"ojs"},{"id":123,"value":"generated_points = {\n let radius = points_radius;\n \n // Random point in circle code from https://stackoverflow.com/questions/32642399/simplest-way-to-plot-points-randomly-inside-a-circle\n function randomPosition(radius) {\n var pt_angle = Math.random() * 2 * Math.PI;\n var pt_radius_sq = Math.random() * radius * radius;\n var pt_x = Math.sqrt(pt_radius_sq) * Math.cos(pt_angle);\n var pt_y = Math.sqrt(pt_radius_sq) * Math.sin(pt_angle);\n return [pt_x, pt_y];\n }\n \n let data_points = [];\n for (let i = 0; i < point_num; i++) {\n let position = randomPosition(radius);\n let name = 'Point ' + i;\n let group = Math.floor(Math.random() * 6);\n let point = { position, name, group };\n data_points.push(point);\n }\n return data_points;\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":89,"value":"function toRadians (angle) {\n return angle * (Math.PI / 180);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":92,"value":"function toDegrees (angle) {\n return angle * (180 / Math.PI);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":14,"value":"THREE = require(\"three@0.90.0/build/three.min.js\")","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W34","stdlib":"1","titling":"auto"}