mapillary-js/doc/docs/main/init.md

id	title
init	Initialization

MapillaryJS comes with a core set of street imagery interaction and visualization features. The Viewer object represents the street imagery viewer on your web page. It exposes methods that you can use to programatically change the view, and fires events as users interact with it.

You can customize the Viewer behavior in different ways. In this guide we will do this at initialization time.

:::info You will learn

• How to activate and deactivate the cover
• How to configure the Viewer through options
• How to configure components through options

:::

Using the Cover

The MapillaryJS cover is a special component that can be activated and deactivated at any time. When the cover is active, MapillaryJS, does not perform any operations at all. We can use the component options to decide if the cover should be active or not when at initialization.

If we specify an image ID in the viewer options, the cover will always be visible initially (but can be hidden automatically through with the cover: false component option).

If we do not specify an image ID in the viewer options the cover will be hidden (resulting in a dark background being shown). In this case, we need another way to tell inform the Viewer about the initial image. We can use the Viewer.moveTo method to do that by calling it with our image ID.

:::tip

Try changing the cover option to false to see how it affects Viewer initialization.

:::

function render(props) {
  let viewer;
  let coverViewer;
  function dispose() {
    if (viewer) {
      viewer.remove();
    }
  }
  function disposeCover() {
    if (coverViewer) {
      coverViewer.remove();
    }
  }

  const style = {height: '400px', width: '50%', display: 'inline-block'};
  const imageId = '3748064795322267';

  function init(opts) {
    const {accessToken, container} = opts;
    const options = {accessToken, container};
    viewer = new Viewer(options);
    viewer.moveTo(imageId).catch(mapillaryErrorHandler);
  }

  function initCover(opts) {
    const {accessToken, container} = opts;
    const options = {
      accessToken,
      component: {cover: true},
      container,
      imageId,
    };
    coverViewer = new Viewer(options);
  }

  return (
    <div>
      <ViewerComponent init={init} dispose={dispose} style={style} />
      <ViewerComponent init={initCover} dispose={disposeCover} style={style} />
    </div>
  );
}

:::info

You can view the complete code for all Viewer initialization behaviors in the Viewer Initialization example.

:::

Viewer Options

The ViewerOptions give us a way to control some behaviors. First, we always specify an access token (when working with data from the Mapillary platform) and a container. The container can be an HTML element ID or an HTMLDivElement.

The other options are optional. We can deactivate things like image tiling, combined panning, and resize tracking. We can also change render mode, transition mode, and camera control mode.

:::tip

Check the difference in pixel resolution when zooming with imageTiling set to true or false.

Try resizing the browser window with trackResize set to true or false. If you set trackResize to false, you can still programatically inform the Viewer that it has been resized by calling the Viewer.resize method.

:::

function render(props) {
  let viewer;
  function dispose() {
    if (viewer) {
      viewer.remove();
    }
  }
  const style = {height: '400px'};
  const imageId = '178975760792906';

  function init(opts) {
    const {accessToken, container} = opts;
    const viewerOptions = {
      accessToken,
      cameraControls: CameraControls.Street,
      combinedPanning: false,
      component: {cover: false},
      container,
      imageId,
      imageTiling: false,
      renderMode: RenderMode.Letterbox,
      trackResize: false,
      transitionMode: TransitionMode.Instantaneous,
    };
    viewer = new Viewer(viewerOptions);
  }

  return <ViewerComponent init={init} dispose={dispose} style={style} />;
}

Component Options

The ComponentOptions can be used to activate or deactivate all components by specifying a boolean value.

Most components also have a configuration. The component configurations give us an opportunity to to do more fine grained component specific configuration. Specifying a component configuration for a component option property means that the component will be activated on initialization in the same way as setting its value to 'true'.

With component options can for example deactivate certain pointer handlers to avoid interfering with the default browser scroll behavior or tell the sequence component to play a sequence immediately on load.

function render(props) {
  let viewer;
  function dispose() {
    if (viewer) {
      viewer.remove();
    }
  }
  const style = {height: '400px'};
  const imageId = '178975760792906';

  function init(opts) {
    const {accessToken, container} = opts;
    const componentOptions = {
      bearing: {size: ComponentSize.Large},
      cache: false,
      cover: false,
      direction: {maxWidth: 300},
      keyboard: {keyZoom: false},
      pointer: {scrollZoom: false},
      sequence: {visible: false, playing: false},
      zoom: true,
    };
    const viewerOptions = {
      accessToken,
      component: componentOptions,
      container,
      imageId,
    };
    viewer = new Viewer(viewerOptions);
  }

  return <ViewerComponent init={init} dispose={dispose} style={style} />;
}

:::info

You can view the complete code for all initial Viewer behaviors in the Viewer Initialization example.

:::

Recap

Now you know how to initialize the MapillaryJS Viewer with different interaction and visualization features by:

• Activating or deactivating the cover component
• Specifying viewer and component options that changes the behavior of MapillaryJS