npm package: 3d-specimen-viewer
Description: This is a React component library to visualize 3D models, with a focus on 3D models of various specimen from scientific collections.
Author: Tim Bernhard
Latest version: 2.0.6

# 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](#3d-specimen-viewer)
  - [Table of contents](#table-of-contents)
  - [Supported files](#supported-files)
  - [.p3v Files](#p3v-files)
    - [Example](#example)
  - [Other files](#other-files)
  - [Developer's Usage](#developers-usage)
    - [Installation](#installation)
    - [Usage](#usage)
  - [Demo](#demo)

## Supported files

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

- gltf,
- glb,
- stl,
- obj,
- ply,
- fbx,
- [p3v](#p3v-files)

wherein the `p3v` file type is a new one specific to this react component, see the [this section](#p3v-files) for details;
it supports using the [https://github.com/ULB-Darmstadt/photogrammetry-viewer](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](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

```bash
yarn add 3d-specimen-viewer
```

or

```bash
npm i 3d-specimen-viewer
```

### Usage

```javascript
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](https://gitlab.ethz.ch/psa/photogrammetry-viewer/3d-specimen-viewer/-/tree/main/3d-specimen-viewer-demo?ref_type=heads).