C3 AI Documentation Home

Tutorial for AI Vision Package

Overview

The AI Vision package allows you to quickly add time-based geospatial visualization and interaction to your application. AI Vision allows you to explore data with highly configurable geospatial visualizations in every C3 AI application. Seamlessly toggle between visualizations to find connections and surface correlations across time and space.​

Installation

Declare a dependency on the aiVision package in your {package}.c3pkg.json. It should look like this:

Text
// examplePackage.c3pkg.json
{
	"name": "examplePackage",
	"description": "My AI Vision Demo",
	"author": "demouser <demo@c3.ai>",
	"dependencies": {
		"aiVision": "8.4.0",
	}
}

## Functionality provided
`aiVision` is a React Library that can be installed through the JavaScript package management tool. This package is the implementation of [AI Vision figma design](https://www.figma.com/design/oNfP2CijpfrVIZxmKaCqjJ/AI-Vision?node-id=3321-9346&t=YjKZ9ToQKhzQOBZ7-0), including a CSS Library of styling tokens, multiple React components as toolkits, and essential helper functions.

`aiVision` leverages the following 3rd party libraries to provide the full service:
- [Cesium](https://cesium.com/) to render 3D geospatial visualization and store 3D objects.
- [Resium](https://resium.reearth.io/) the React wrapper of Cesium.
- [Mapbox](https://www.mapbox.com/) as 2D tile provider.

Usage

File path for custom components should be: {package}/ui/c3/src/customInstances/{package}.ComponentName.tsx.

Text
import React, { useCallback, useRef } from 'react';

// Import react components and helper functions from `cesium-style-kit` package.
import { Legend, Tooltip, SpeedTimeLineControl, useIonAccessToken } from '@c3/cesium-style-kit';

// Local import
import MapComponent from './MapComponent';

const WrapperComponent = () => {
    const viewerRef = useRef(null);
    const tokenIsSet = useIonAccessToken();
    if(!tokenIsSet) </>;
    return (
        <>
            <MapComponent viewerRef={viewerRef} />
            <Legend title={"AI Vision Title"} />
            <Tooltip content=[/** {content of tooltip} **/] />
            <SpeedTimeLineControl viewerRef={viewerRef} />
        </>
    )

}

In most cases as the application grows, there will be reuseable functions and components. To host reusable code,

  1. (Recommended) Create a folder under {package}/ui/c3/src/{package}
  2. Put reusable components or functions inside this folder. For example, we have a helper function at: {package}/ui/c3/src/{package}/helpers.ts.
Text
const myHelperFunction = () => {};
export { myHelperFunction };
  1. Import the reusable code from your custom components:
Text
import { myHelperFunction} from '@c3/app/ui/src/{package}/helpers';

Available components

Legend and LegendLabel

The Legend component allows you to display a descriptive text for the different colors, shapes and icons used in an assigned UI element. Legend acts as a container that takes title and groups of LegendLabel. See the example below:

Text
<Legend
  title={'Legend'}
  groups={{
    legendGroups: [
      {
        name: 'Entity Identity',
        labels: [
          <LegendLabel truncate={true} label={'Aircraft'} color={'#ffffff'} icon={'plane'} onClick={onClick} />,
        ],
      },
      {
        name: 'Color',
        labels: [
          <LegendLabel label={'Success'} color={'#00ff00'} shape={'circle'} onClick={onClick} />,
          <LegendLabel label={'Warning'} color={'#ADD8E6'} shape={'line'} onClick={onClick} />,
        ],
      },
    ],
    isLegendGroups: false,
  }}
/>

Tooltip

Tooltip is a component to display informative text when users hover over or click on a map element. To activate a tooltip, the developer needs to specify an HTML Node as the container of who this tooltip is rendered on top of (most likely the cesium-widget element), and the location as pixel values. When activated, Tooltip can display a header, a sub-header, and a list of key-value pairs as additional information. See the example below:

Text
<Tooltip
  container={"cesium-widget"}
  tooltipPosition={positionFromState}
  title={"UA 2474"}
  subtitle={"From SFO to EWR"}
  content={[
    {
      key:  "Scheduled Departure",
      value:  "8:30 AM"
    },{
      key:  "Flight Status",
      value:  "On Time",
   }]}
/>

SpeedTimeLineControl

Speed Timeline Control is a dropdown element that controls the play speed for the timeline. Developer can set a list of speed by pass in an array to speedOptions, or leave it unset to use the default options. See the example below:

Text
<SpeedTimeLineControl
    viewerRef={viewerRef}
    speedOptions={[1, 2, 3, 4, 5]}
/>

Styling map element

The cesium-style-kit package provides a list of styling tokens matching the C3 design specifications. To use them, import and invoke them as in the example below:

Text
import { styles, toCesiumColor } from '@c3/cesium-style-kit';

const hoverEvent = useCallback((movement, viewer) => {
    const pickedFeature = viewer.scene.pick(movement.endPosition);
    if (pickedFeature?.id?.model) {
        pickedFeature.id.model.silhouetteColor = toCesiumColor(styles.entityHoverBorderColor);
    }
}, []);

For more information on what this kit includes, follow along on cesium style kit explanations.

CSS Styling: Timeline and Map control

The cesium-style-kit package provides a modern and professional UX experience on top of Cesium styling. To style your component matching cesium-style-kit look and feel, import the following .scss files.

Text
TBD

Integrate with C3 application

Cesium and Resium import

Resium is the React Wrapper for Cesium. Importing from Resium is the recommended way of building your React application with Cesium as the wrapper will handle component lifecycle and hot module replacement. To use Resium and Cesium, please see the following example:

Text
import React, { useCallback, useRef } from 'react';
import { Viewer } from 'resium';
import { Cartesian3 } from 'cesium';

const MapComponent = (props) => {
    const onRefChange = useCallback((node) => {
	  if (node?.cesiumElement !==  undefined && selectedEntity === undefined) {
		// Take the raw Cesium `viewer` object from `node.cesiumElement`.
		const viewer = node.cesiumElement;
		props.viewerRef.current = viewer;
		viewer.camera.setView({
			destination:  Cartesian3.fromDegrees(-75, 45, 500000),
		});
	}});

    return (
        <>
            <Viewer ref={(nodes) => onRefChange(nodes)} />
        </>
    )
}

Plug into C3 UI Framework

To render React components in C3 UI Framework, developer needs to define an entry point of the React world as a single React component, and follow the naming convention of that component as: ModuleName.ComponentName.tsx. For example, if WrapperComponent from the previous "Usage" section is called MyCesiumDemo.WrapperComponent.tsx, then you can plug it into a content frame with the following snippet:

Text

{
	"type" : "UiSdlConnected<UiSdlContentFrame>",
	"component" : {
		"showTop": true,
		"showBottom": false,
		"topBar": {"id": "AiVision.ContentFrameTopBarSegmented" },
		"content": [{
			"type": "UiSdlComponentContainer",
			"column": 12,
			"childComponent": { "id": "AiVision.CustomComponent" }
		}]
	}
}

Related tutorial and documentation

Refer to following documentation to learn more about how to integrate custom components with C3 UI Framework.

Was this page helpful?