Three.js Migration Audit: 19 deprecated API calls mapped across application source modules

[akshitcodes]

@natacha-beck @bryancaron

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.

[ayushk687]

@akshitcodes please assignthis issue to me

[akshitcodes]

Following up with a few additional migration notes I found while working through this more carefully.

A few points that expand the migration surface beyond the initial 19 call sites:

1. Additional compatibility blockers not in the original audit:

   • geometry.addAttribute(...) in loading.js and views.js needs to become setAttribute(...)
   • MeshPhongMaterial({ ambient: ... }) in loading.js will need updating, since the ambient material property was removed in later three.js versions
   • renderDepth usage in loading.js will likely need to move to renderOrder or renderer-managed sorting

2. The dependency swap is also a build-system problem.
   BrainBrowser builds through Grunt concatenation into browser-global bundles, so replacing the vendored three.js copy is not a simple import change. Preserving the current bundle shape for downstream consumers seems like an important constraint.

3. For transparency validation, issue Shapes not responding well to opacity slider #310 looks directly relevant:
   Shapes not responding well to opacity slider #310

   It documents opacity failures on multi-shape datasets and notes partial improvement with a newer three.js version, which suggests the upgrade itself may change part of the transparency behavior even before BrainBrowser-specific fixes are applied.

Adding these here because they seem useful for the migration regardless of how the work gets assigned.

[mayu888]

This repo is largely unmaintained now. You might want to check out https://github.com/mayu888/neuroviz
instead.

[natacha-beck]

Please see comment on #368