lush-collabs-asset v1.5.0

LushCollabsAsset

Live Demo

Running the example

To view example.html requires a webserver (because of cross-origin restrictions when loading environment files). First build bundle.js by running yarn run build then run yarn run server and open http://localhost:8080/example.html in your browser to see the example running.

Build instructions

• Install node.js
• Run yarn install from this directory to install dependencies
• Run yarn start to start a watch-compile-reload development server

Release build

• Run yarn run build from this directory to build the library for production

Using as a module

• Add LushCollabsAsset as a dependency using its git repository as the source

  yarn add git+https://gitlab+deploy-token-118071:NBg3xktRcoymxs9sRdum@gitlab.com/LUSHDigital/fed/packages/lush-collabs-asset

• Copy the assets directory from the repo and place somewhere accessible on your webserver. This part is important because the assets folder contains the lighting environments and it cannot run without them

• Load the module with require. LushCollabsAsset is exposed as a CommonJS module, so you can load it with:

  const LushCollabsAsset = require('lush-collabs-asset');

• Initialize it with a canvas and the path to the assets folder you copied earlier

  let lushCollabsAsset = new LushCollabsAsset(canvas, 'path-to-assets-folder');

• When you run your project you'll either now see an interactive 3D sphere (yey it works! 🎉) or a black empty canvas 😫. If you see a black canvas, this is almost certainly because it cannot see the assets folder you copied over. Make sure you've got the correct path to the assets folder in new LushCollabsAsset(canvas, *path-to-assets-folder*); and that the assets folder is accessible on your server. If you get stuck at this point let me know and we can debug together, however it probably depends on the specifics of whatever server setup you have

API

Main API entry point is src/LushCollabsAsset.ts, see example.html for an example usage

class LushCollabsAsset {

    /**
     * Return the name set by setCreationName() or `undefined` if unset
     */
    get creationName();

    /**
     * @param canvas Canvas element to render to
     * @param assetPath Path to assets folder, required for loading environment files
     * @param limitDeviceRatio Set a maximum device ratio – use this to disable rendering at native resolution on high-dpi displays
     */
    constructor(canvas: HTMLCanvasElement, assetPath: string = 'assets', limitDeviceRatio?: number);

    /**
     * Apply vote options in the object format, e.g.
     * `{'when_do_you_bathe': ['morning'], 'feeling': [grounding', 'comforting'] }`
     * @param voteOptions 
     */
    applyVoteOptions(voteOptions: VoteOptions);

    /**
     * Apply vote options via long string format, for example
     *
     * "colors:black,colors:purple,feeling:grounding,fragrance:citrus,ingredients:coconut_milk"
     * @param longCode
     */
    applyVoteOptionsLongCode(longCode: string);

    /**
     * Apply vote options via short-code string format, for example "gpTPiAAC"
     * @param longCode
     */
    applyVoteOptionsShortCode(shortCode: string);

    /**
     * Generates an mp4 (x264) video
     * An options object isn't required, however it can be used to control the duration and output quality
     * 
     * For reference, an example of high-quality options
     * {
     *  fps: 60,
     *  width: 1024,
     *  height: 1024,
     * }
     * 
     * And low quality
     * {
     *  fps: 30,
     *  width: 768,
     *  height: 768
     * }
     * 
     * Render-time increases rapidly w.r.t output dimensions 
     * 
     * If a video capture is currently in progress when this method is called, the original capture is cancelled and replaced with the new one
     * 
     * Canceling a video capture will trigger `onFailure` with the reason 'canceled'
     * 
     * @returns If started successfully, a cancellation token otherwise `null`. Cancel video capture with `token.capture()`
     */
    captureVideo(
        onProgress: (progress: number) => void,
        onFailure: (reason: string) => void,
        onComplete: (animation: Blob, times: { total: number, canvas: number, encoding: number }, config: VideoEncoderConfig) => void,
        options: {
            /**
             * Framerate, e.g. 60 or 30
             */
            fps?: number,
            width?: number,
            height?: number,

            /**
             * Use light-bloom effect when rendering (default `true`)
             */
            bloom?: boolean,

            /**
             * Video duration in seconds
             */
            duration?: number,

            /**
             * Log debug messages to console while capturing
             */
            logging?: boolean,

            /**
             * Rotate camera around object for the duration (default `true`)
             */
            autoRotate?: boolean,

            /**
             * Time speed (default 1)
             * 
             * time multiplier when recording; e.g a value of 0.5 would create a slow motion effect where time passes half as fast
             */
            timeSpeed?: number,
        } = {}
    ): { cancel(): void } | null;

    /**
     * If a video capture is in progress, calling this will cancel the video capture
     * Calling when no capture is in progress is safe and has no effect
     * 
     * Canceling a video capture triggers that capture's on-failure callback with the reason `canceled`
     */
    cancelCaptureVideo();

    /**
     * @return `true` if a video capture is currently in progress
     */
    isCapturingVideo(): boolean;

    /**
     * Capture a snapshot of the canvas with increased render quality settings
     * The image dimensions will match the canvas width and height
     * @param options
     * @return a png image in data-url format, i.e. data:image/png;base64,...
     */
    captureImageAsDataURL(options: {
        width?: number,
        height?: number,
        bloom?: boolean
    });
    
    /**
     * Set the creation name shown over the creation
     * @param name utf8 string, if name is null then the creation name will be hidden
     */
    setCreationName(name?: string);

    /**
     * Call this when the canvas container changes size so that the WebGL content is resized too
     */
    resizeCanvas();

    /**
     * Starts WebGL canvas rendering if it's stopped (you can call this repeatedly without issue)
     */
    startRendering();

    /**
     * Call this to disable WebGL canvas rendering. Call this before removing and disposing of the canvas element (in methods like `componentWillUnmount`)
     * 
     * You can restart rendering again by calling `startRendering()`
     * 
     * You can call with repeatedly without issue
     */
    stopRendering();

    /**
     * Given a vote options string in long format, e.g. "colors:black,feeling:grounding", parse it and return a VoteOptions object
     * @param voteOptionsLongCode
     */
    static parseLongCode(voteOptionsLongCode: string): VoteOptions;

    /**
     * Given a vote options string in short-code format, e.g. "3_aptQHG", parse it and return a VoteOptions object
     * @param voteOptionsLongCode
     */
    static parseShortCode(shortCode: string);

    /**
     * Given a set of vote options, generate the equivalent long string format
     * @param voteOptions
     */
    static generateLongCode(voteOptions: VoteOptions): string;

    /**
     * Given a set of vote options, generate the equivalent short-code string
     * @param voteOptions
     */
    static generateShortCode(voteOptions: VoteOptions): string;

    /**
     * Short-code utility class
     */
    static ShortCode;

}