aleph-viewer/aleph

Aleph is a 3D object viewer and annotation/measurement tool built with A-Frame, AMI, StencilJS, and Ionic

Aleph

Aleph is a 3D object viewer and annotation/measurement tool built with A-Frame, AMI, StencilJS, and Ionic

  

• Website
• Scope
• Getting Started
• Contributing
• Feedback
• Documentation
• License

Website

Visit the Aleph demo page to try it out.

Scope

• Usable as a web component within any page/framework and has a Universal Viewer integration
• Has a supporting Control Panel (a separate web component) showing associated settings for a given mesh or volume
• Straight-forward to debug, using a single source of truth and unidirectional data flow (redux)
• Themable to allow customised colour schemes (css variables)
• Encapsulates 3D rendering logic in a well-defined component model, with pre-existing community support/adoption (A-Frame)
• Utilises the component model to extensibly display 3D media file types (GLTF+DRACO, DICOM)
• Renders 3D scenes declaratively, decoupling the presentation layer from the application layer
• Permits annotation of points on a 3D mesh or volume with a title and description
• Permits measurement of lengths and angles, with the potential to be extended to areas and volumes
• Permits annotation/measurement data to be stored/retrieved as json
• Permits slice and volume views of volumetric data, with axis/slice selection and point cloud windowing controls
• Permits panning, rotating, and animated transitions between annotations/measurements
• Has "in-scene" annotation/measurement tools as opposed to overlaid, permitting future AR/VR/XR use cases

Getting Started

Clone the repository and run npm install

Dev Builds

For development with readable sources and hot reloading run:

npm run build:dev

Production Builds

For minified production builds run:

npm run build

View on localhost

npm start

Contributing

Read below to learn how to take part in improving Aleph:

• Fork the repository and run the examples from source
• Get familiar with Code of Conduct
• Read our guide to contributing
• Find an issue to work on and submit a pull request
  • First time contributing to open source? Pick a good first issue to get you familiar with GitHub contributing process.
  • First time contributing to Aleph? Pick a beginner friendly issue to get you familiar with codebase and our contributing process.
  • Want to become a Committer? Solve an issue showing that you understand Aleph objectives and architecture. Here is a good list to start.
• Could not find an issue? Look for bugs, typos, and missing features.

Feedback

Read below how to engage with Aleph community:

• Join the discussion on Slack.
• Ask a question, request a new feature and file a bug with GitHub issues.
• Star the repository to show your support.

Documentation

Web Components

• al-angle-editor
• al-console
• al-control-panel
• al-edge-editor
• al-graph-editor
• al-node-editor
• al-node-list
• al-settings
• al-tabs
• al-url-picker
• al-viewer

Aleph can be used to display GLTF files and DICOM series. GLTF can be used in conjunction with DRACO compression.

To annotate/measure an object, open the "Settings" tab in the control panel and check "Enable Node Placement". Clicking on a 3D object will create a node which can be given a title and description. Nodes can be used as points of interest or can be connected via edges. With a node selected, SHIFT + Click to create an edge between that and another node. Edges can be used for measurement and can also be labeled with a title and description. Units of measurement can be changed in the control panel. SHIFT + Click between edges to measure angles.

The two top-level web components are <al-control-panel> and <al-viewer>. <al-control-panel> wraps a tabs-based interface containing <al-url-picker>, <al-settings>, <al-graph-editor>, and <al-console>. <al-viewer> contains the A-Frame scene and all 3D rendering logic. It also contains a Redux store that acts as single source of truth for the viewer and control panel. <al-viewer> can be used independently of <al-control-panel>, which can be lazy loaded to provide additional options.

License

• MIT

aleph's Issues

Placing an angle can cause strange node label background sizing

Steps to reproduce:

1. Load a mesh
2. Place three nodes
3. Place two edges with one node in common
4. Place an angle between the two edges
5. Create three additional edges.

The third additional edge (i.e., edge 6 overall) will have bugged extra-wide light gray background behind the dark gray background. Weird!

Camera position/rotation broken when using A-Frame 1.0.4

https://github.com/aframevr/aframe/releases/tag/v1.0.4

Not sure which change has caused this. Is fine is v1.0.3.

zooming out with aleph in orbit mode results in scrolling down the page

zooming does not result in scrolling up because (I suppose) the preview is at the top of the page already. But it is a distracting problem especially for meshes

problems with node size and node label font size

some images have nodes and font that are way too big or way too small. Im not sure how font and node size is currently being determined. It would seem that if was determined via as a constant relative to bounding box dimensions this should be less of an issue.

measurement tools not working on some meshes

measurement tools are not working on certain meshes: for instance the UF Sifrippus tooth: https://morphosource-demo.lib.duke.edu/concern/media/000005227?locale=en.

Could have something to do with it being a very small tooth

Very large (in polygon/vertex count) meshes perform poorly

Very large meshes (like 16 million polygon meshes) currently perform more poorly in Aleph than in other Three.js-based web GLTF mesh viewers. This seems to be due to the computational overhead of the raycaster calculating when the cursor intersects with the mesh.

The large mesh branch is an example of an experimental fix to this issue, disabling the raycaster for the orbit camera but not the trackball camera. Performance is much higher for orbit than trackball when the cursor intersects with mesh surface. This of course also causes an additional issue where when using the orbit camera, it is impossible to interact with nodes in any way (including highlighting them).

One approach to solving this issue would be to disable the raycaster unless a user has 'enable node placement' switched on, though this would cause the above issue with being unable to highlight previously placed nodes. Alternately maybe the node placement switch should be replaced with some kind of 'node mode' that toggles both visibility of and placement of nodes.

I'll be trying to address this issue as I'm able.

node editing ability takes too long to enable

The issue has to do with editing the name of nodes or deleting them (as opposed to moving them on the object).

We should separate the "node panning" function from "node editing" functions. It often takes a long time for the node to become editable after clicking on it because aleph rotates and pans to the node which can take a while for a big mesh. There's no reason those two functions need to be tied to each other.

In the node list, we should have two buttons: 1 says "zoom to node" or "pan to node". the other says "edit". Seems like you should be able to click "edit" and change the node name or delete it without incurring the cost of rotating and zooming the specimen.

It seems best to separate them because we will always have big meshes or files. I just dont see any reason to connect the two functions. When you want to edit the node, that's what you want to do, not pan then edit. Its counter intutive when your goal is editing the node name and instead you have to rotate and pan before you can do that.

Add onclick event to annotation dots that can be listened for in the containing page

This is useful for driving an experience that aleph is embedded into.

Very small (in real-world units) GLTF/GLB meshes cause problems for viewing and annotation

See the attached mesh, which is roughly disc-shaped and has a size of around ~1.7 millimeters as the widest diameter. This particular mesh was not correctly scaled, but it is completely possible to have objects at this size. The src/Constants.ts camera near value (0.05) is not large enough to account for a mesh like this, and on initial load the mesh appears too close to the camera to be viewed.

That can be changed easily enough to something like 0.0001 to address this, but placing annotations on the example mesh produces this error: "THREE.DirectGeometry: Faceless geometries are not supported." Though it seems to relate to a very different issue, this stack exchange answer suggests this particular error may also be caused by the small size of the mesh.

4-glb.glb.zip

Ionic syles not being applied in Firefox

When viewing https://aleph-viewer.com in Firefox 70.0.1 (64-bit) on Windows 10 and clicking on the "Nodes" tab I see unstyled links and input fields.

Here's how it looks in latest Chrome:

Styling problems can also be seen on the "Source" tab, where in Chrome the selection box extends to the full width of the sidebar, and in Firefox it doesn't. Also the input field correctly has a grey background in Chrome, whereas it doesn't in Firefox.

Nice project name! 👍🏻

Option for annotation dots to only appear when selected

This is useful when driving the experience from an external menu.

Make Volume view default instead of sliced

Multiple people I tried showing aleph-viewer's volume models just said "loads forever, and then displays a texture". I think you would avoid confusion over the capabilities if the default view would be the volume :)

Add ability to annotate whole object as well as distinct parts of it

This is useful when describing properties of an object as a whole.

Add ability to change annotation label background colour

This is useful when Aleph is part of a larger application with a distinct style/colour scheme of its own.