NDAView SDK

Tích hợp NDAView trong phần tử HTML với NDAView-SDK

Mô tả

NDAView SDK cho phép người dùng nhúng công cụ xem ảnh 360° của NDAView vào phần tử HTML của người dùng.

Cách sử dụng

Để tích hợp công cụ xem ảnh 360° của NDAView trên các ứng dụng web của bạn, bạn cần phải thêm code snippet dưới đây trong tệp HTML của bạn.Code snippet này sẽ nhúng công cụ xem ảnh 360° của NDAView qua thư viện NDAView-SDK.

<!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</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"
    />
    <meta
      name="keywords"
      content="NDAView, 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

Tham số	Loại	Bắt buộc	Ví dụ	Mô tả
`apiKey`	string	yes	`YOUR_API_KEY`	API_KEY của bạn để gọi API.
`lang`	object	no	Xem chi tiết ↓	Tooltip mô tả của các phần tử trong giao diện của NDAView-sdk.
`navbar`	boolean	no		Bật thanh công cụ với phóng to thu nhỏ ảnh, quay hướng.
`panorama`	object	no	Xem chi tiết ↓	Cấu hình ảnh 360 mạng định để hiển thị nếu ko lấy được ảnh và các thuộc tính của ảnh.
`loadingImg`	string	no	https://view.ndamaps.vn/logo.svg	Ảnh loading .
`defaultZoomLvl`	number	no		Cấu hình zoom mạng định của ảnh.
`defaultYaw`	number	no	yaw * 180 / Math.PI	Cấu hình góc yaw mạng định của ảnh.
`defaultPitch`	number	no	pitch * 180 / Math.PI	Cấu hình góc pitch mạnh định của ảnh.
`container`	HTMLElement	yes		Element DOM gắn với viewer. Có thể truyền `useRef(...).current`.
`adapter`	`AdapterConstructor \| [AdapterConstructor, any]`	yes	Xem chi tiết ↓	Dùng để cấu hình và ghi đè cấu hình của thư viện `@photo-sphere-viewer`. Bạn có thể dùng class PhotoAdapter của chúng tôi hoặc viết lại kết thừa class `@photo-sphere-viewer/equirectangular-tiles-adapter` .
`plugins`	`Array<PluginConstructor \| [PluginConstructor, any]>`	yes	Xem chi tiết ↓	Dùng để sử dụng các plugins của NDAView-sdk.

`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

Để sử dụng các plugins banj cần khởi tạo plugin đó

const { VirtualTourPlugin, CompassPlugin } = NdaviewVN_Viewer.plugins;

CompassPlugin

Là plugins để hiển thị la bàn. có chức năng hiển thị phương hướng của góc nhình và các node gần điểm đang xem

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

Cấu hình plugin

  {
    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,
  }

Tham số	Loại	Bắt buộc	Ví dụ	Mô tả
`size`	string	no	'120px'	Kích thước của la bàn.
`position`	string \| [string, string]	no	'top left'	Vị trí của la bàn.
`backgroundSvg`	string	no		SVG được sử dụng làm nền của la bàn.
`coneColor`	string	yes	'rgba(255, 255, 255, 0.5)'	Màu sắc của hình nón la bàn.
`navigation`	boolean	no	true	Cho phép nhấp vào la bàn để xoay trình xem.
`navigationColor`	string	no	'rgba(255, 0, 0, 0.2)'	Màu sắc của nón dẫn đường.
`hotspots`	CompassHotspot[]	no	color?: 'rgba(255, 0, 0, 0.2)'	Các chấm nhỏ có thể nhìn thấy trên la bàn (sẽ chứa mọi điểm đánh dấu có dữ liệu "la bàn").
`hotspotColor`	string	no	'rgba(0, 0, 0, 0.5)'	Màu mặc định của điểm nóng.
`className`	string	no		Các lớp CSS được thêm vào phần tử compass.

thông tin

Bạn có thể xem ví dụ chi tiết ở đây Example

PlanPlugin

Là plugin để hiển thị minimap với các chức năng thu nhỏ phóng to và điểm điểm mà điểm ảnh của bạn đang ở đó

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

Cấu hình plugin:

{
  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,
  },
}

Tham số	Loại	Bắt buộc	Ví dụ	Mô tả
`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 đồ.

thông tin

Bạn có thể xem ví dụ chi tiết ở đây Example

TrackPlugin

Là plugin để hiển thị được line và các point điểm ảnh mà NDAView đã ghi nhận

 [TrackPlugin, {}]

thông tin

Bạn có thể xem ví dụ chi tiết ở đây Example

VirtualTourPlugin

Là plugin để hiển thị trình xem ảnh 360°

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

Cấu hình plugin

{
  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
}

Tham số	Loại	Bắt buộc	Ví dụ	Mô tả
`dataMode`	string	no	`client` \| `server`	Cấu hình chế độ dữ liệu.
`positionMode`	string	no	`manual` \| `gps`	Cấu hình chế độ vị trí.
`speed`	number	no		Cấu hình tốc độ.
`renderMode`	string	no	`3d` \| `2d` \| `markers`	Cấu hình chế độ hiển thị của liên kết.
`nodes`	VirtualTourNode	no		Các nút ban đầu (chế độ máy khách).
`startNodeId`	string	no		Id của nút ban đầu, nếu không được xác định thì nút đầu tiên sẽ được sử dụng.
`preload`	boolean	no	true	Tải trước ảnh toàn cảnh được liên kết.
`transitionOptions`	TransitionOptions	no	`{ showLoader: true, speed: '20rpm', fadeIn: true, rotation: true }`	Cấu hình chuyển đổi giữa các nút. Có thể là một lệnh gọi lại.
`linksOnCompass`	boolean	no	true	Nếu plugin Compass được bật, sẽ hiển thị các liên kết trên la bàn.
`updateCoordinatesPlan`	boolean	no	true	Cập nhật kế hoạch tọa độ.
`arrowStyle`	VirtualTourArrowStyle	no		Kiểu mũi tên toàn cục.
`markerPitchOffset`	number	no		Độ lệch điểm đánh dấu.
`arrowPosition`	string	no	`top` \| `bottom`	Vị trí của mũi tên.
`arrowEnabled`	boolean	no	true	Hiển thị mũi tên.
`arrowsPosition`	ArrowsPositionOptions	no		Cấu hình của hộp chứa mũi tên.
`map`	MapOptions	no		Cấu hình đặc biệt khi sử dụng MapPlugin.

Phương thức

Tên	Tham số	Mô tả
`onLoadNode()`		Cấu hình chế độ dữ liệu.
`getNode()`	`getNode?: (nodeId: string) => VirtualTourNode \| Promise<VirtualTourNode>`	Chức năng để lấy một nút (chế độ máy chủ).

thông tin

Bạn có thể xem ví dụ chi tiết ở đây Example

ViewModePlugin

Là plugin chuyển đổi giữa các chế độ xem street và fly

  [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 SDK

Mô tả​

Cách sử dụng​

Photo​

lang​

panorama​

adapter​

Plugins​

CompassPlugin​

PlanPlugin​

TrackPlugin​

VirtualTourPlugin​

ViewModePlugin​

Definitions​

CompassHotspot​

GpsPosition​

CssSize​

PlanHotspotStyle​

PlanLayer​

PlanHotspot​

VirtualTourNode​

TransitionOptions​

VirtualTourArrowStyle​

ArrowsPositionOptions​

MapOptions​

Mô tả

Cách sử dụng

Photo

`lang`

`panorama`

`adapter`

Plugins

CompassPlugin

PlanPlugin

TrackPlugin

VirtualTourPlugin

ViewModePlugin

Definitions

CompassHotspot

GpsPosition

CssSize

PlanHotspotStyle

PlanLayer

PlanHotspot

VirtualTourNode

TransitionOptions

VirtualTourArrowStyle

ArrowsPositionOptions

MapOptions