| 1 | # Viv [](https://badge.fury.io/js/%40hms-dbmi%2Fviv)
|
| 2 |
|
| 3 | A library for multiscale visualization of high-resolution multiplexed tissue data on the web. Directly renders Bio-Formats-compatible Zarr and OME-TIFF.
|
| 4 | Written in JavaScript and built on Deck.gl with modern web technologies.
|
| 5 |
|
| 6 | ## Installation
|
| 7 |
|
| 8 | ```bash
|
| 9 | $ npm install @hms-dbmi/viv
|
| 10 | ```
|
| 11 |
|
| 12 | ## About
|
| 13 |
|
| 14 | Viv is a JavaScript library providing utilities for rendering primary imaging data. Viv supports WebGL-based multi-channel rendering of both pyramidal and non-pyramidal images. The rendering components of Viv are provided as Deck.gl layers, making it easy to compose images with existing layers and efficiently update rendering properties within a reactive paradigm.
|
| 15 |
|
| 16 | More details can be found in our preprint describing the Viv library and related work. Please cite this preprint in your research:
|
| 17 |
|
| 18 | > Trevor Manz, Ilan Gold, Nathan Heath Patterson, Chuck McCallum, Mark S Keller, Bruce W Herr II, Katy Börner, Jeffrey M Spraggins, Nils Gehlenborg, "Viv: Multiscale Visualization of High-resolution Multiplexed Tissue Data on the Web." **OSF Preprints** (2020), [doi:10.31219/osf.io/wd2gu](https://doi.org/10.31219/osf.io/wd2gu)
|
| 19 |
|
| 20 | ## Avivator
|
| 21 |
|
| 22 | Also included in this repository is [`Avivator`](http://avivator.gehlenborglab.org), a lightweight "batteries-included"
|
| 23 | WebGL viewer for remote imaging data. Avivator is a purely client-side program that only requires access to
|
| 24 | Bio-Formats "raw" Zarr or OME-TIFF data over HTTP. To use Avivator with your own data, please see the data preparation
|
| 25 | [tutorial](tutorial/README.md). Initial load time for OME-TIFFs can be optimized by generating a special `offsets.json`
|
| 26 | file containing byte offsets for the associated binary data. For more information, see the
|
| 27 | [documentation](http://viv.gehlenborglab.org/#ome-tiff-loading).
|
| 28 |
|
| 29 |
|
| 30 |
|
| 31 | ## Development
|
| 32 |
|
| 33 | ```bash
|
| 34 | $ git clone https://github.com/hms-dbmi/viv.git
|
| 35 | $ cd viv && npm install # install deps for viv library
|
| 36 | $ npm run install:avivator # install deps for avivator app
|
| 37 | $ npm start # Starts rollup build (for Viv) & dev server for Avivator
|
| 38 | ```
|
| 39 |
|
| 40 | Please install the [Prettier plug-in](https://prettier.io/docs/en/editors.html) for your preferred editor.
|
| 41 | (Badly formatted code will fail on Travis.)
|
| 42 |
|
| 43 | Due to [difficulties](https://github.com/hms-dbmi/viv/issues/103) around compiling shaders on Travis, unit tests and layer lifecycle
|
| 44 | tests are run locally as a pre-push hook. Travis runs a test build, linting, and prettier.
|
| 45 |
|
| 46 | To run unit and integration tests locally, use `npm test`. For full prodcution test (including linting and formatting checks),
|
| 47 | use `npm run test:prod`.
|
| 48 |
|
| 49 | ## Build
|
| 50 |
|
| 51 | - `@hms-dbmi/viv` library: `npm run build`
|
| 52 | - `Avivator` viewer: `npm run build:avivator`
|
| 53 |
|
| 54 | ## Publish
|
| 55 |
|
| 56 | To bump the version number, clean up/update the CHANGELOG.md, and push the tag to Github,
|
| 57 | please run `npm version [major | minor | patch]` depending on which you want. Then run `./publish.sh` to publish the package/demo.
|
| 58 |
|
| 59 | ## Browser Support
|
| 60 |
|
| 61 | We support both WebGL1 and WebGL2 contexts, which should give near universal coverage. Please file an issue if you find a browser in which we don't work.
|
| 62 |
|
| 63 | ## Documentation
|
| 64 |
|
| 65 | Please navigate to [viv.gehlenborglab.org](http://viv.gehlenborglab.org) to see full documenation.
|