Three.js Migration Audit: 19 deprecated API calls mapped across application source modules #372
Description
Summary
Building on #368, I've done a detailed audit of the application source files (not the vendored three.js itself) to map every deprecated API call that would break when upgrading from r69 to a modern three.js release. This should serve as a reference checklist for the migration.
Result: 19 deprecated calls across 3 files. Two files (color.js, annotations.js) are clean.
1. matrix.getInverse() → matrix.copy(source).invert() (removed r123)
| File | Line | Current Code |
|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 196 | inv.getInverse(model.matrix) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 618 | inv_matrix.getInverse(intersect_object.matrixWorld) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 793 | new THREE.Matrix4().getInverse(model.matrix) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 807 | new THREE.Matrix4().getInverse(model.matrix) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 978 | inverse.getInverse(model.matrix) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 982 | inverse.getInverse(model.matrix) |
6 occurrences — all in rendering.js.
2. object.applyMatrix() → object.applyMatrix4() (renamed r125)
| File | Line | Current Code |
|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 198 | model.applyMatrix(inv) |
1 occurrence — direct rename.
3. new THREE.Geometry() → new THREE.BufferGeometry() (removed r125)
| File | Line | Current Code | Function |
|---|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 270 | new THREE.SphereGeometry(radius) | drawDot() |
| src/brainbrowser/surface-viewer/modules/rendering.js | 380 | new THREE.Geometry() | gridHelper() |
| src/brainbrowser/surface-viewer/modules/rendering.js | 432 | new THREE.Geometry() | drawLine() |
This is the most complex migration item. THREE.Geometry allowed direct manipulation via .vertices.push() and .colors.push() — BufferGeometry requires typed Float32Array attributes via .setAttribute().
Note: loading.js (L712) and views.js (L256) already use BufferGeometry ✅
4. geometry.vertices / geometry.colors direct mutation (removed with Geometry)
| File | Lines | Current Code |
|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 387-389 | geometry.vertices.push(new THREE.Vector3(...)) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 391 | geometry.colors.push(horizontal_color, horizontal_color) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 396-399 | geometry.vertices.push(new THREE.Vector3(...)) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 400 | geometry.colors.push(vertical_color, vertical_color) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 433-434 | geometry.vertices.push(start.clone()) / end.clone() |
These are all inside gridHelper() and drawLine() — the same functions that use THREE.Geometry.
5. THREE.LinePieces → THREE.LineSegments (removed r110)
| File | Line | Current Code |
|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 403 | THREE.Line.call(grid, geometry, material, THREE.LinePieces) |
| src/brainbrowser/surface-viewer/modules/rendering.js | 442 | new THREE.Line(geometry, material, THREE.LinePieces) |
| src/brainbrowser/surface-viewer/modules/views.js | 282 | new THREE.Line(wire_geometry, material, THREE.LinePieces) |
| src/brainbrowser/surface-viewer/modules/loading.js | 757 | new THREE.Line(geometry, material, THREE.LinePieces) |
4 occurrences across 3 files. Migration: replace with new THREE.LineSegments(geometry, material).
6. GridHelper.setColors() (removed r137)
| File | Line | Current Code |
|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 338 | grid.setColors(color_center_line, color_grid) |
Migration: Pass colors in the constructor — new THREE.GridHelper(size, divisions, color1, color2). Note: second param changed from step size to number of divisions.
7. event.wheelDelta (deprecated DOM API)
| File | Line | Current Code |
|---|---|---|
| src/brainbrowser/surface-viewer/modules/rendering.js | 1056 | event.wheelDelta |
Uses 'mousewheel' and 'DOMMouseScroll' events (L1079-1080). Should migrate to the standard 'wheel' event with event.deltaY.
Summary
| Deprecated API | Count | Files | Severity |
|---|---|---|---|
| getInverse() | 6 | rendering.js | 🔴 Crashes on modern three.js |
| THREE.Geometry + vertices/colors | 5 | rendering.js | 🔴 Class removed entirely |
| THREE.LinePieces | 4 | rendering.js, views.js, loading.js | 🔴 Constant removed |
| applyMatrix() | 1 | rendering.js | 🟡 Easy rename |
| GridHelper.setColors() | 1 | rendering.js | 🟡 API redesigned |
| GridHelper constructor | 1 | rendering.js | 🟡 Param semantics changed |
| wheelDelta | 1 | rendering.js | 🟢 Works but deprecated |
| Total | 19 | 3 files |
Already Modern
- loading.js uses BufferGeometry and typed arrays
- views.js uses BufferGeometry for wireframes
- color.js — no three.js API calls
- annotations.js — no deprecated patterns
I'm planning to use this as the basis for a GSoC proposal and will be submitting a PR for the simpler fixes (LinePieces → LineSegments, applyMatrix rename) as a starting point.