Search code, repositories, users, issues, pull requests…

Bivot is a web component for embedding Bandicoot Shimmer View images.

Example:

Bivot is provided as a React component. Bivot is also JavaScript embeddable.

Shimmer View content for Bivot can be created easily using the Bandicoot web app.

Features:

  • Show how light plays over a material, including fine texture and gloss
  • Control the view and lighting angle using mouse position or device tilt
  • Wide support across browsers and devices (mobile and desktop)
  • Embed local Shimmers or remotely hosted Shimmers
  • Physically based rendering on GPU via WebGL
  • Fine-tune the Shimmer appearance using the Bandicoot web app editor

Demo

Examples of Bivot being used on the web can be found in the Bandicoot material gallery.

Installing

To install the Bivot React NPM package, run the following:

Bivot React has two peer dependencies: react, and @material-ui/core. If not already present, these also need to be installed in your local or global NPM environment, for example via the following command:

Embedding – React

A <Bivot> element embeds a single Shimmer View, specified via the materialSet property. The materialSet can be local or on the web.

Multiple <Bivot> components can be embedded on the same page, if different id properties are set.

The width and height of a <Bivot> component can be overridden responsively.

An example showing these concepts is below.

A complete example app is provided in the example directory of the source repo.

Props

Embedding – JavaScript

You can also embed Bivot into a web page using JavaScript. For example:

By default, the Shimmer is responsive, and fills the width of its container at a fixed aspect ratio.

Customisable parts of the embed snippet include:

  • @v3.19.21 – The version of Bivot JS to use
  • https://publish.bandicootimaging.com.au/b1ec2d90/biv_gallery/material-set.json – Specify the Shimmer to embed

A complete example page with responsive layout is provided at src/bivot-js/example/embed-bivot-js.html in the source repo.

Tilt control

Bivot asks the user to grant tilt control on mobile environments which block it by default (iOS). Tilt control permissions can only be granted over https, not http.

Developer environment

  1. Install NPM
  2. Create a Github personal access token
  3. Add your Github personal access token to your ~/.npmrc
  4. Check out bivot
  5. In the top level bivot folder, run npm install
  6. In src/bivot-js, run npm install

The last step relies on both ~/.npmrc (for your login, not checked in) and src/bivot-js/.npmrc (to know where to read the Github Three.js package, is checked in).

TODO: Figure out a recipe that doesn’t require a Github personal access token for read-only access to the Bandicoot packge fork of Three.js.

To publish new versions of the Bivot NPM package:

  1. Create an NPM personal access token and add it to your ~/.npmrc
  2. The Bandicoot team will need to grant write access on the Bivot package to your NPM account
  3. The release recipe is currently documented in our internal developer notes

Access keys may expire depending on the expiry settings when created or if they haven’t been used for a while (e.g. 1 year).

License

Bivot is released under the MIT license (see the LICENSE file). Licenses for additional code adapted into Bivot are in the THIRD-PARTY.md file.