3d-specimen-viewer

3D Specimen Viewer

This is a React component library to visualize 3D models, with a focus on 3D models of various specimen from scientific collections.

Table of contents

• 3D Specimen Viewer
  • Table of contents
  • Supported files
  • .p3v Files
    • Example
  • Other files
  • Developer's Usage
    • Installation
    • Usage
  • Demo

Supported files

Currently, the following file-types as detected by extensions are supported:

• gltf,
• glb,
• stl,
• obj,
• ply,
• fbx,
• p3v

wherein the p3v file type is a new one specific to this react component, see the this section for details; it supports using the https://github.com/ULB-Darmstadt/photogrammetry-viewer with only one file provided.

.p3v Files

The .p3v file-type is a custom file-type introduced by this component. The motivation for introducing a custom file-type is the limitation in various collection databases of uniquely associating files that belong together. Such a set of files belonging together is, for example, given for photogrammetry, where many 2D images come together to construct one 3D image.

The https://github.com/ULB-Darmstadt/photogrammetry-viewer is included as one of the viewers of this component. It allows to view the 3D image side-by-side with the source 2D images. As a consequence, it requires this full set of files.

This .p3v file-type is a zip compressed directory, which must contain

• an .xml file, which will be used as the camera and scan information (at the moment, only the xml format from Agisoft is supported),
• a .gltf or .glb file, which will be used as the source for the 3D viewer part,
• and the 2D images used to produce the 3D file. These may be in any format and folder, in theory, and simply be consistent in their filenames with what the scan information xml provides. However, for performance reasons, and since it is possible that the files suggested by the xml are not unambiguous, we recommend having them in a folder called redof, with lowercase file extensions png or jpg
• (optional) an image called hdr.png or hdr.jpg, which will be used as the sky-box image in the 3D-viewer

More files are allowed in the ZIP; however, they are simply ignored.

[!IMPORTANT] The first files with the respective file endings are used (for the xml and 3D files). Correspondingly, make sure no other files with the same ending are included in the package. Similarly, there should not be unrelated files with the same identifier as the 2D images.

Example

In minimum, an example file could be build like this:

minimal-example.zip.p3v

.
├── camera.xml
├── example-p3v-3dfile.glb
└── redof
    ├── image_000.jpg
    ├── image_001.jpg
    ├── image_002.jpg
    └── ...

the following would be valid just as well:

larger-example.zip.p3v

.
├── cameras.xml
├── CamPos.txt
├── Model
│   ├── example-p3v-3dfile.gltf
│   ├── example.psx
│   ├── example.mtl
│   ├── example.png
│   └── ...
└── images-2d
    ├── image_000.PNG
    ├── image_001.PNG
    ├── image_002.PNG
    └── ...

Nonetheless, we recommend to build the zip file in the minimum configuration, in order to reduce the filesize and therewith the loading times when displaying the .p3v file.

Other files

For completeness, this viewer also serves a small basis of additional files that are not concerned with 3d, such as images or video. The motivation here is to be a bit easygoing with collection databases employing this viewer in some way which is not guarding against calling it for other file types (Specify, for example, where access to the viewer could be implemented as a button (web-link) on the same level as any other asset; notably, one might consider integrating this React component into Specify, but that petition was unfortunately declined). Since the viewer's primary purpose is to be a 3d-viewer, these other file types shall not be documented further here.

Developer's Usage

Since this repository contains a React component, the following documentation is tailored towards developers and assumes basic knowledge of what you are doing.

Installation

yarn add 3d-specimen-viewer

or

npm i 3d-specimen-viewer

Usage

import { SpecimenViewer3D } from "3d-specimen-viewer";

// ...your react javascript code...

return (
  <your-react-jsx-code>
    <SpecimenViewer3D src="https://link.to/your/specimens-3d-file">
  <your-react-js-code>
)

Optionally, you may also pass the parameter fileName and/or fileType to help determine the type of 3D file specified.

Demo

This repository comes with a demo in ./3d-specimen-viewer-demo.