NDAView.vn SDK

Integrate ndaview.vn in HTML element with NDAView-SDK

Description

ndaview.vn SDK allows users to embed ndaview.vn 360° image viewer into user's HTML element.

Usage

To integrate ndaview.vn 360° image viewer on your web applications, you need to add the code snippet below in your HTML file. This code snippet will embed ndaview.vn 360° image viewer via NDAView-SDK library.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="./logo.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Khám phá đường phố Việt Nam | NDAView.vn</title>
    <meta
      name="description"
      content="Khám phá đường phố tại Việt Nam bằng công nghệ 360° độc đáo với NDAView.vn"
    />
    <meta
      name="keywords"
      content="ndaview.vn, xem duong pho viet nam, vietnam ndaview, xem duong pho, street, view, kham pha duong pho, duong, pho"
    />
    <meta property="og:image" content="./logo_ngang.png" />
    <meta property="twitter:image" content="./logo_ngang.png" />
    <script src="https://view.ndamaps.vn/sdk/ndaviewvn.umd.js"></script>
    <link
      rel="stylesheet"
      href="https://view.ndamaps.vn/sdk/style.css"
      type="text/css"
    />
  </head>

  <body style="margin: 0; padding: 0;">
    <div
      id="root"
      style="width: 100dvw; height: 100dvh; padding: 0; margin: 0;"
    ></div>
    <script type="text/javascript">
      const container = document.getElementById("root");
      const { Photo } = NdaviewVN_Viewer;
      const { PhotoAdapter } = NdaviewVN_Viewer.adapter;
      const { VirtualTourPlugin, CompassPlugin } = NdaviewVN_Viewer.plugins;

      const BASE_PANORAMA = {
        baseUrl: "https://view.ndamaps.vn/loader_hd.png",
        width: 1280,
        cols: 2,
        rows: 1,
        tileUrl: () => null,
      };

      const photo = new Photo({
        apiKey: "YOUR_API_KEY",
        lang: {
          zoom: "Thu phóng",
          zoomOut: "Thu nhỏ",
          zoomIn: "Phóng to",
          moveUp: "Tiến",
          moveDown: "Lùi",
          moveLeft: "Trái",
          moveRight: "Phải",
          description: "Chi tiết",
          download: "Tải xuống",
          fullscreen: "Toàn màn hình",
          loading: "Đang tải...",
          menu: "Danh mục",
          close: "Đóng",
          twoFingers: "Sử dụng 2 ngón tay để điều hướng",
          ctrlZoom: "Sử dụng Ctrl + scroll để thu phóng ảnh",
          loadError: "Không thể tải hình ảnh 360 lúc này",
          webglError: "Trình duyệt của bạn không hỗ trợ WebGL",
        },
        container,
        navbar: false,
        panorama: BASE_PANORAMA,
        loadingImg: "https://view.ndamaps.vn/logo.svg",
        adapter: [
          PhotoAdapter,
          {
            showErrorTile: false,
            baseBlur: false,
            resolution: 64,
            shouldGoFast: () => false,
          },
        ],
        defaultZoomLvl: 0,
        defaultYaw: 0,
        defaultPitch: 0,
        plugins: [
          [
            CompassPlugin,
            {
              size: "34px",
              position: ["top", "right"],
            },
          ],
          [
            VirtualTourPlugin,
            {
              arrowEnabled: false,
              preload: true,
            },
          ],
        ],
      });
      photo
        .getPlugin(VirtualTourPlugin)
        .setCurrentLatLng({ lng: 105.836501728, lat: 21.037001424 }, true);
    </script>
  </body>
</html>

Photo

Parameter	Type	Required	Example	Description
`apiKey`	string	yes	`YOUR_API_KEY`	Your API_KEY to call the API.
`lang`	object	no	See details ↓	Tooltip description of elements in the ndaview.vn-sdk interface.
`navbar`	boolean	no		Enable toolbar with image zoom in/out, rotate orientation.
`panorama`	object	no	See details ↓	Configure the default 360 image to display if the image and its properties are not available.
`loadingImg`	string	no	https://view.ndamaps.vn/logo.svg	Image loading.
`defaultZoomLvl`	number	no		Configure default zoom of the image.
`defaultYaw`	number	no	yaw * 180 / Math.PI	Configure the default yaw angle of the image.
`defaultPitch`	number	no	pitch * 180 / Math.PI	Configure the image's strong pitch angle.
`container`	HTMLElement	yes		DOM element associated with viewer. Can pass `useRef(...).current`.
`adapter`	`AdapterConstructor \| [AdapterConstructor, any]`	yes	See details ↓	Used to configure and override the configuration of the `@photo-sphere-viewer` library. You can use our PhotoAdapter class or rewrite it by inheriting the `@photo-sphere-viewer/equirectangular-tiles-adapter` class.
`plugins`	`Array<PluginConstructor \| [PluginConstructor, any]>`	yes	See details ↓	Used to use ndaview.vn-sdk plugins.

`lang`

{
  "zoom": "Zoom",
  "zoomOut": "Zoom Out",
  "zoomIn": "Zoom In",
  "moveUp": "Move Up",
  "moveDown": "Move Down",
  "moveLeft": "Move Left",
  "moveRight": "Move Right",
  "description": "Description",
  "download": "Download",
  "fullscreen": "Fullscreen",
  "loading": "Loading",
  "menu": "Menu",
  "close": "Close",
  "twoFingers": "Use 2 fingers to navigate",
  "ctrlZoom": "Use Ctrl + scroll to zoom in and out",
  "loadError": "Load error",
  "hintWheel": "Drag or swipe left - right - up - down to view 360 images",
  "webglError": "Your browser does not support WebGL"
}

`panorama`

{
  "baseUrl": "https://view.ndamaps.vn/loader_hd.png",
  "width": 1280,
  "cols": 2,
  "rows": 1,
  "tileUrl": null
}

`adapter`

adapter:[
  PhotoAdapter, {
    showErrorTile: false,
    baseBlur: false,
    resolution: 64,
    shouldGoFast: () => false
}]

Plugins

To use plugins you need to initialize that plugin.

const { VirtualTourPlugin, CompassPlugin } = NdaviewVN_Viewer.plugins;

CompassPlugin

Is a plugin to display compass. It has the function of displaying the direction of the viewing angle and the nodes near the viewing point.

  [CompassPlugin, {
    size: "34px",
    position: ["top", "right"]
  }]

Plugin configuration

  {
    size: '120px',
    position: ['top', 'left'],
    backgroundSvg: compass,
    coneColor: 'rgba(255, 255, 255, 0.5)',
    navigation: true,
    navigationColor: 'rgba(255, 0, 0, 0.2)',
    hotspots: [],
    hotspotColor: 'rgba(0, 0, 0, 0.5)',
    className: null,
  }

Parameter	Type	Required	Example	Description
`size`	string	no	'120px'	Size of compass.
`position`	string \| [string, string]	no	'top left'	Position of the compass.
`backgroundSvg`	string	no		SVG used as compass background.
`coneColor`	string	yes	'rgba(255, 255, 255, 0.5)'	Color of compass cone.
`navigation`	boolean	no	true	Allow clicking on compass to rotate viewer.
`navigationColor`	string	no	'rgba(255, 0, 0, 0.2)'	Color of the cone.
`hotspots`	CompassHotspot[]	no	color?: 'rgba(255, 0, 0, 0.2)'	Small dots visible on the compass (will contain any markers with "compass" data).
`hotspotColor`	string	no	'rgba(0, 0, 0, 0.5)'	Default color of hotspot.
`className`	string	no		CSS classes added to the compass element.

info

You can see detailed example here Example

PlanPlugin

Is a plugin to display minimap with zoom in and out functions and point to the point where your pixel is located

  [
    PlanPlugin,
    {
      defaultZoom: 10,
      visibleOnLoad: true,
      pinSize: 80,
      enabledLocate: false,
      size: {width: '180px', height: '120px'}
    }
  ],

Plugin configuration:

{
  coordinates: null,
  bearing: 0,
  size: {width: '300px', height: '200px'},
  position: ['bottom', 'left'],
  visibleOnLoad: true,
  pinImage: pin,
  pinSize: 35,
  enabledLocate: true,
  onMaximized: () => {},
  onMinimize: () => {},
  onChangeCenter: () => {},
  spotStyle: {
    size: 15,
    image: null,
    color: 'white',
    hoverSize: null,
    hoverImage: null,
    hoverColor: null,
    hoverBorderSize: 4,
    hoverBorderColor: 'rgba(255, 255, 255, 0.8)',
  },
  defaultZoom: 15,
  layers: [{
    urlTemplate: null,
    attribution: OSM_ATTRIBUTION,
    name: OSM_LABEL,
  }],
  configureLeaflet: null,
  buttons: {
    maximize: true,
    close: true,
    reset: true,
  },
}

Parameter	Type	Required	Example	Description
`coordinates`	GpsPosition	no		Vị trí GPS của bức ảnh toàn cảnh hiện tại.
`bearing`	string \| number	no	0	Độ lệch xoay áp dụng cho chốt trung tâm.
`size`	CssSize	no	'300px * 200px'	Kích thước của bản đồ.
`position`	string \| [string, string]	no	'bottom left'	Vị trí của bản đồ.
`visibleOnLoad`	boolean	no	true	Hiển thị bản đồ khi tải ảnh toàn cảnh đầu tiên.
`pinImage`	string	no		SVG hoặc URL hình ảnh được sử dụng cho trung tâm (phải là hình vuông).
`pinSize`	number	no	35	Kích thước của điểm trung tâm.
`spotStyle`	PlanHotspotStyle	no		Kiểu mặc định của điểm truy cập.
`defaultZoom`	number	no	15	Mức thu phóng mặc định.
`layers`	PlanLayer	no	OpenStreetMap	Xác định các lớp có sẵn.
`configureLeaflet`	(map: Map)	no		Cho phép bạn cấu hình Leaflet từ đầu.
`hotspots`	PlanHotspot	no		Điểm truy cập trên bản đồ.
`buttons`	Object	no		Cấu hình các nút bản đồ.

info

You can see detailed example here Example

TrackPlugin

Is a plugin to display lines and pixel points that ndaview.vn has recorded.

 [TrackPlugin, {}]

info

You can see detailed example here Example

VirtualTourPlugin

Is a plugin to display 360° photo viewer

  [VirtualTourPlugin, {
    arrowEnabled: false,
    preload: false
  }]

Plugin configuration

{
  dataMode: 'server',
  positionMode: 'gps',
  renderMode: '3d',
  apiKey: null,
  nodes: null,
  getNode: getNode,
  onLoadNode: () => {},
  startNodeId: null,
  preload: true,
  updateCoordinatesPlan: true,
  speed: null,
  transitionOptions: {
    showLoader: false,
    speed: 500,
    zoomTo: PSV_DEFAULT_ZOOM,
    fadeIn: true,
    rotation: true,
  },
  linksOnCompass: true,
  getLinkTooltip: null,
  markerStyle: null,
  arrowStyle: DEFAULT_ARROW,
  markerPitchOffset: null,
  arrowPosition: null,
  arrowsPosition: {
    minPitch: 0.3,
    maxPitch: Math.PI / 2,
    linkOverlapAngle: Math.PI / 4,
    linkPitchOffset: -0.1,
  },
  map: null,
  arrowEnabled: false
}

Parameter	Type	Required	Example	Description
`dataMode`	string	no	`client` \| `server`	Configure data mode.
`positionMode`	string	no	`manual` \| `gps`	Configure location mode.
`speed`	number	no		Speed configuration.
`renderMode`	string	no	`3d` \| `2d` \| `markers`	Configure the visibility of the link.
`nodes`	VirtualTourNode	no		Initial buttons (client mode).
`startNodeId`	string	no		Id of the initial node, if not defined then the first node will be used.
`preload`	boolean	no	true	Preload linked panoramas.
`transitionOptions`	TransitionOptions	no	`{ showLoader: true, speed: '20rpm', fadeIn: true, rotation: true }`	Configures the transition between buttons. Can be a callback.
`linksOnCompass`	boolean	no	true	If the Compass plugin is enabled, it will display links on the compass.
`updateCoordinatesPlan`	boolean	no	true	Update coordinate plan.
`arrowStyle`	VirtualTourArrowStyle	no		Global arrow style.
`markerPitchOffset`	number	no		Marker offset.
`arrowPosition`	string	no	`top` \| `bottom`	Position of the arrow.
`arrowEnabled`	boolean	no	true	Show arrow.
`arrowsPosition`	ArrowsPositionOptions	no		Configuration of the arrow box.
`map`	MapOptions	no		Special configuration when using MapPlugin.

Method

Name	Parameter	Description
`onLoadNode()`		Configure data mode.
`getNode()`	`getNode?: (nodeId: string) => VirtualTourNode \| Promise<VirtualTourNode>`	Function to get a button (server mode).

info

You can see detailed example here Example

ViewModePlugin

Is a plugin that switches between street and fly views

  [ViewModePlugin, {
    position: ["bottom", "right"],
  }]

export type ViewModePluginConfig = {
  /**
   * size of the compass
   * @default '120px'
   */
  size?: string;

  /**
   * position of the compass
   * @default 'top left'
   */
  position?: string | [string, string];

  /**
   * CSS class(es) added to the compass element.
   */
  className?: string;

  /**
   * Show lines and points in track plugin in view mode only
   * @default null
  */
  onlyMode?: 'street' | 'fly';
};

Definitions

CompassHotspot

type CompassHotspot = ExtendedPosition & {
    color?: string;
};

GpsPosition

type GpsPosition = [number, number, number?];

CssSize

type CssSize = {
    width: string;
    height: string;
};

PlanHotspotStyle

type PlanHotspotStyle = {
  /**
   * Size of the hotspot
   * @default 15
   */
  size?: number;
  /**
   * SVG or image URL used for hotspot
   */
  image?: string;
  /**
   * Color of the hotspot when no image is provided
   * @default 'white'
   */
  color?: string;
  /**
   * Size on mouse hover
   * @default null
   */
  hoverSize?: number;

  onMaximized?: () => void,
  onMinimize?: () => void,
  onChangeCenter?: (c: any) => void,
  /**
   * SVG or image URL on mouse hover
   * @default null
   */
  hoverImage?: string;

  enabledLocate?: boolean;
  /**
   * Color on mouse hover
   * @default null
   */
  hoverColor?: string;
  /**
   * Size of the border shown on mouse hover
   * @default 4
   */
  hoverBorderSize?: number;
  /**
   * Color of the border shown on mouse hover
   * @default 'rgba(255, 255, 255, 0.8)'
   */
  hoverBorderColor?: string;
};

PlanLayer

type PlanLayer = {
  urlTemplate?: string;
  layer?: Layer;
  name?: string;
  attribution?: string;
};

PlanHotspot

type PlanHotspot = PlanHotspotStyle & {
  /**
   * GPS coordinates of the marker
   */
  coordinates: GpsPosition;

  /**
   * Unique identifier for the {@link SelectHotspot} event
   */
  id?: string;

  /**
   * Tooltip visible on the map
   */
  tooltip?: string | {content: string; className?: string};
};

VirtualTourNode

type VirtualTourNode = {
  id: string;
  panorama: any;
  /**
   * short name of the node (links tooltip, gallery)
   */
  name?: string;
  /**
   * caption visible in the navbar
   */
  caption?: string;
  /**
   * description visible in the side panel
   */
  description?: string;
  /**
   * data used for this panorama
   */
  panoData?: PanoData | PanoDataProvider;
  /**
   * sphere correction to apply to this panorama
   */
  sphereCorrection?: SphereCorrection;
  /**
   * links to other nodes
   */
  links?: VirtualTourLink[];
  /**
   * GPS position
   */
  gps?: GpsPosition;
  /**
   * thumbnail for the gallery
   */
  thumbnail?: string;
  /**
   * additional markers to use on this node
   */
  markers?: Array<MarkerConfig & {gps?: GpsPosition}>;
  /**
   * configuration of the hotspot when using the MapPlugin
   */
  map?: Partial<Point> & Omit<MapHotspot, 'id' | 'yaw' | 'distance'>;
  /**
   * configuration of the hotspot when using the PlanPlugin
   */
  plan?: Omit<PlanHotspot, 'id' | 'coordinates'>;
  /**
   * Any custom data you want to attach to the node
   */
  data?: any;
};

TransitionOptions

transitionOptions?:| Pick<VirtualTourTransitionOptions, 'showLoader' | 'speed' | 'fadeIn' | 'rotation'>| ((
  toNode: VirtualTourNode,
  fromNode?: VirtualTourNode,
  fromLink?: VirtualTourLink
) => VirtualTourTransitionOptions);

VirtualTourArrowStyle

type VirtualTourArrowStyle = {
  /**
   * URL of an image used for the arrow
   */
  image?: string;
  /**
   * Use a custom element for the arrow
   */
  element?: HTMLElement | ((link: VirtualTourLink) => HTMLElement);
  /**
   * CSS classes added to the element
   */
  className?: string;
  /**
   * Size of the arrow
   */
  size?: Size;
  /**
   * CSS properties to set on the arrow
   */
  style?: Record<string, string>;

  /** @deprecated */
  color?: string;
  /** @deprecated */
  hoverColor?: string;
  /** @deprecated */
  outlineColor?: string;

  enabledTooltip?: boolean;
};

ArrowsPositionOptions

arrowsPosition?: {
  /**
   * (3D mode) Minimal vertical view angle
   * @default 0.3
   */
  minPitch?: number;
  /**
   * (3D mode) Maximal vertical view angle
   * @default PI/2
   */
  maxPitch?: number;
  /**
   * (3D mode) Make transparent links that are close to each other
   * @default PI/4
   */
  linkOverlapAngle?: number;
  /**
   * (2D+GPS mode) vertical offset applied to link markers, to compensate for viewer height
   * @default -0.1
   */
  linkPitchOffset?: number;
}

MapOptions

 map?: {
   /**
    * URL of the map
    */
   imageUrl: string;
   /**
    * size of the map in pixels
    */
   size?: Size;
   /**
    * bounds of the map in GPS coordinates (minX, minY, maxX, maxY)
    */
   extent?: [number, number, number, number];
 };

NDAView.vn SDK

Description​

Usage​

Photo​

lang​

panorama​

adapter​

Plugins​

CompassPlugin​

PlanPlugin​

TrackPlugin​

VirtualTourPlugin​

ViewModePlugin​

Definitions​

CompassHotspot​

GpsPosition​

CssSize​

PlanHotspotStyle​

PlanLayer​

PlanHotspot​

VirtualTourNode​

TransitionOptions​

VirtualTourArrowStyle​

ArrowsPositionOptions​

MapOptions​

Description

Usage

Photo

`lang`

`panorama`

`adapter`

Plugins

CompassPlugin

PlanPlugin

TrackPlugin

VirtualTourPlugin

ViewModePlugin

Definitions

CompassHotspot

GpsPosition

CssSize

PlanHotspotStyle

PlanLayer

PlanHotspot

VirtualTourNode

TransitionOptions

VirtualTourArrowStyle

ArrowsPositionOptions

MapOptions