42 | Online 3D Viewer with Next.js 43 |
44 |46 | This is a work in progress! If you want to add or 47 | correct these examples, please submit a pull request! 48 |
49 |50 | There was a lack of documentation for Online 3D Viewer 51 | and how to use it with React and Next.js, so I've made 52 | this guide to help others encountering the same issue. 53 | I'll show some examples of how you can use the Online 3D 54 | Viewer and while also explaining some errors and issues 55 | I encountered and how to resolve them. This is very much 56 | a work in progress and isn't perfect, if you have any 57 | feedback or additional advice, please submit a pull 58 | request 59 |
60 |61 | To setup this project, clone the repo, npm install the 62 | packages and run the server with npm run dev. I've only 63 | tested this with stl and 3dm files, other files may 64 | produce unique issues, if you encounter them, please let 65 | me know 66 |
67 |70 | Setting up Online 3D Viewer with your Next app: 71 |
72 |73 | First, install the npm package from 74 | https://www.npmjs.com/package/online-3d-viewer. Import 75 | the package into your project with `import * as OV from 76 | "online-3d-viewer"` 77 |
78 |79 | Secondly, on order for this package to work in your 80 | project, make sure you have the libs folder in your 81 | public folder, as shown in this repo. These are the 82 | external packages used by Online-3D-Viewer to load the 83 | different types of 3D file client side.{" "} 84 | 85 | THE PACKAGE WILL NOT WORK WITHOUT THESE PRESENT. 86 | 87 |
88 |89 | This is all the setup you'll need and we'll now look at 90 | the different ways you can use the viewer and load in 91 | files 92 |
93 |Example 1: A basic 3D viewer
96 |97 | This is a very basic example of how you can have a file 98 | input, upload a file and have it display in the 3D 99 | viewer. This example will also clean up correctly, 100 | avoiding memory leaks that can happen while using this 101 | package with React . Using this example's component, you 102 | can easily spin up multiple different viewers at the 103 | same time and passing different files into each one, 104 | though I would be careful doing so for reasons mentioned 105 | at the bottom of this page. 106 |
107 |108 | See the "Basic3DViewer" component in the components 109 | folder to see how this was constructed. I've left 110 | annotated notes explaining how everything works but will 111 | add some additional comments here 112 |
113 |114 | {" "} 115 | You may notice that the method of loading files seems 116 | over complicated. As the viewer loads files in using a 117 | FileList, you don't need to extract the file, put it in 118 | state, then use a DataTransfer object to recreate a 119 | FileList. However, this method works better if you're 120 | holding File Interfaces in state, e.g. with Zustand, and 121 | passing them between components, as this way the 122 | original file input DOM element doesn't need to be on 123 | the page. This is useful using UI patterns like Wizards, 124 | where a user may upload a file on one step and then the 125 | app may need the file again on another step despite the 126 | fact that DOM input is gone 127 |
128 |140 | Example 2: Different methods to load files 141 |
142 |143 | There are two methods that I've used to load files into 144 | the viewer: LoadModelFromFileList and 145 | LoadModelFromInputFiles. If you need to load a file 146 | uploaded through a DOM input by the user, use 147 | LoadModelFromFileList and use the prior example. If you 148 | want to load the file from a URL, use the example below. 149 |
150 |151 | As with the prior example, please see the 152 | "ViewerWithUrls" component and see the annotated code. 153 |
154 |181 | Example 3: Using viewer methods with your own UI 182 |
183 |184 | Obviously, most users will likely want to use this 185 | package for more than just viewing 3D files. 186 | Unfortunately, there isn't any real documentation on how 187 | to do so and what can be done. I'll show some examples 188 | here but until there is more documentation, I'd advise 189 | you to read the code, particularly 190 | https://github.com/kovacsv/Online3DViewer/blob/master/source/engine/viewer/viewer.js 191 | and 192 | https://github.com/kovacsv/Online3DViewer/blob/master/source/engine/viewer/embeddedviewer.js 193 | to see what's possible 194 |
195 |196 | I haven't commented the code for this component, it's 197 | fairly self explanatory. To better understand why 198 | certain parameters are being passed into each function, 199 | see the source code linked above 200 |
201 |Tips and things to avoid
214 |-
215 |
- 216 | You must wait for the component to mount with 217 | useEffect before instantiating the viewer as the 218 | viewer calls window on initialisation which is only 219 | present in the browser, not node 220 | 221 |
- 222 | The package isn't well documented so there are two 223 | ways to figure out what functions can be used: read 224 | the source code or log the Viewer object and examine 225 | in the browser 226 | 227 |
- 228 | Instantiating the viewer object creates a canvas DOM 229 | element that we need to hold onto with React's 230 | useRef 231 | 232 |
- 233 | Another important thing is that you need to 234 | correctly clean up the instantiated EmbeddedViewer. 235 | You can't do this by just using something like 236 | `viewerRef = null` in the useEffect cleanup function 237 | as the DOM element will be cleaned up but not all 238 | the references to the model and the arrays that hold 239 | the geometry data. As such, we need to explicitly 240 | remove these. The code I have at the moment was 241 | haphazardly slapped together and likely contains 242 | redundancy, if you come up with a better solution, 243 | please let me know but it does correctly reduce the 244 | memory usage 245 | 246 |
- 247 | Even with the above code, the JS garbage collector 248 | is not the fastest so if you're running multiple 249 | instances of the viewer, be careful to stagger them 250 | if possible, as your user's browsers may run out of 251 | memory, particularly on lower end devices 252 | 253 |
- 254 | Even if you somehow don't manage to run out of 255 | memory, you will likely run out of WebGL contexts 256 | (see 257 | https://github.com/kovacsv/Online3DViewer/issues/320) 258 | which is capped at anywhere between 8-12 depending 259 | on the device and the browser 260 | 261 |
- 262 | If you need to pass a file around between components 263 | where the initial input may be lost, consider 264 | storing the file in state using something like 265 | Zustand 266 | 267 |