Hotspots and Animation

Want to open a door? Here's how.

Rich data streams

Sometimes you'll want a user to interact with a stream, but in a way that provides accessibility and easy localization. Interactions contained within the stream can be servicable, but they're unlikely to be picked up by a screen reader and correcting a typo means altering the visualization.

The Palette SDK addresses this with "rich data streams". The rich data stream API allows integrators to subscribe to a series of data packets which describe the visualization in a way that can be leveraged by the UI. The most common example of this is to display animation node that allow you to interact with the scene by clicking a HTML element positioned using info from the stream (as demonstrated below).

LibZL takes care of keeping the data in sync with the visualization, so all you have to do is subscribe to the data, and implement the interactions. If you allow the interactive video stream below to time out, you can see how image based interactions work exactly the same way. Enabling support for hot spots in image mode simply requires richDataStreamConfig.enable2DODSupport to be set to true in the connection options, which it is here.

Example

import LibZL, {DataSourceID} from "@zerolight-core/libzl";
import  { useEnvironment,    
          useZLBolt, 
          useZLBoltStreamState, 
          useCamera,
          ZLBoltStreamOverlay, 
          ZLBoltStreamContainer } from "@zerolight-core/libzl-react"

We're also re-using the <ConnectionWidget/> here previously defined in the basic demo.

Also provided for you here is an animation widget that demonstrates the basic animation methods. Note that the third argument passed to the setAnimation method on the close call makes the door snap shut immediately, without any animation. Both setAnimation and triggerAnimation also take a callback as a final parameter, to allow you to respond to an animation completing.

const AnimationWidget = () => {
    const zlbolt = useZLBolt();
    
    return <WidgetGroup>
                <button onClick={() => zlbolt.setAnimation("DoorFR", true)}>
                    Open Door
                </button>
                <button onClick={() => zlbolt.setAnimation("DoorFR", false, true)}>
                    Close Door
                </button>
                <button onClick={() => zlbolt.triggerAnimation("DoorFR")}>
                    Toggle door
                </button>
        </WidgetGroup>
}

Finally, hotSpotStyle provides some basic CSS to display the spots as white circles, but you can display the nodes in keeping with your own applicaiton.

Live Editor

// Example Component to render animation hotspots const Hotspots = () => { const zlbolt = useZLBolt(); const state = useZLBoltStreamState(); const ready = state == StreamConnectionState.Ready; const channel = DataSourceID.DS_ANIMATIONTRIGGERPOINTS; const [points, setPoints] = React.useState(); useEffect(() => { let richApi = pointsData = undefined; ready && zlbolt.getRichDataStreamAPI((error, api) => { richApi = api; }); if (!richApi) { return () => {}; } onSpotsData = (data) => { pointsData = data; if (pointsData) { setPoints({ points: { ...pointsData.points } }); } } richApi.subscribeAll(channel, onSpotsData); return () => { richApi.unsubscribeAll(channel, onSpotsData); }; }, [zlbolt, ready]); if (!zlbolt || state !== StreamConnectionState.Ready) { return <></>; } onClick = (point) => { zlbolt.triggerAnimation(point.animation, false, () => { // callback triggered when animation completes }); } // can use properties of each point here to decide if it should be // visible or not. In this example, we're only displaying points // marked as exterior and only if they're facing the camera isVisible = (point) => { return point.exterior && point.viewing_angle > 110 && point.cam_dir_point_dir_dotp > 0.3; } return (<ZLBoltStreamOverlay> {points && Object.values(points.points).filter(isVisible).map((p) => { return <div key={p.id} onClick={() => onClick(p)} style={{ top: (100 - p.viewport_pos.y * 100) + "%", left: p.viewport_pos.x * 100 + "%", ...hotSpotStyle }}/>; })} </ZLBoltStreamOverlay>); } HotspotDemo = () => { // libZL doesn't support SSR if (useIsBrowser()){ const zlbolt = new LibZL().zlbolt("palettedocs"); return (<ZLBolt zlbolt={zlbolt} options={defaultDemoOptions}> <ConnectionWidget/> <ZLBoltStreamContainer/> <Hotspots/> <AnimationWidget/> </ZLBolt>); } return (<div>Unsupported</div>); } render(<HotspotDemo/>)

//  Example Component to render animation hotspots
const Hotspots = () => {
    const zlbolt = useZLBolt();
    const state = useZLBoltStreamState();
    const ready = state == StreamConnectionState.Ready;

    const channel = DataSourceID.DS_ANIMATIONTRIGGERPOINTS;

    const [points, setPoints] = React.useState();

    useEffect(() => {
        let richApi = pointsData = undefined;
        
        ready && zlbolt.getRichDataStreamAPI((error, api) => {
            richApi = api;
        });

        if (!richApi) {
            return () => {};
        }
        
        onSpotsData = (data) => {
            pointsData = data;
            if (pointsData) {
                setPoints({ points: { ...pointsData.points } });
            }
        }
        
        richApi.subscribeAll(channel, onSpotsData);

        return () => {
            richApi.unsubscribeAll(channel, onSpotsData);
        };
    }, [zlbolt, ready]);


    if (!zlbolt || state !== StreamConnectionState.Ready) {
        return <></>;
    }

    onClick = (point) => {
        zlbolt.triggerAnimation(point.animation, false, () => {
            // callback triggered when animation completes       
        });
    }

    // can use properties of each point here to decide if it should be 
    // visible or not. In this example, we're only displaying points
    // marked as exterior and only if they're facing the camera
    isVisible = (point) => {
        return  point.exterior &&
                point.viewing_angle > 110 && 
                point.cam_dir_point_dir_dotp > 0.3;
    }

    return (<ZLBoltStreamOverlay>
            {points && Object.values(points.points).filter(isVisible).map((p) => {
                return <div key={p.id} 
                            onClick={() => onClick(p)} 
                            style={{    
                                    top: (100 - p.viewport_pos.y * 100) + "%", 
                                    left: p.viewport_pos.x * 100 + "%", 
                                    ...hotSpotStyle
                                }}/>;
            })}
          </ZLBoltStreamOverlay>);
}


HotspotDemo = () => {
    // libZL doesn't support SSR
    if (useIsBrowser()){

        const zlbolt = new LibZL().zlbolt("palettedocs");
        
        return (<ZLBolt zlbolt={zlbolt} options={defaultDemoOptions}>   
                    <ConnectionWidget/> 
                    <ZLBoltStreamContainer/>
                    <Hotspots/>
                    <AnimationWidget/>
                </ZLBolt>);
    }

    return (<div>Unsupported</div>);
}

render(<HotspotDemo/>)

Result

Loading...

note

Provisioning for this demo is light so there may be some delays getting a stream.