Streetview SDK

Integrate Streetview in HTML element with Streetview-SDK

Description

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

tip

When using that, just use our Enterprise Dashboard or guild API Key to create your API Key try for free!

Usage

To integrate streetview.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 streetview.vn 360° image viewer via Streetview-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 | Streetview.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 Streetview.vn"
    />
    <meta
      name="keywords"
      content="streetview.vn, xem duong pho viet nam, vietnam streetview, 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://streetview.vn/sdk/streetviewvn.umd.js"></script>
    <link
      rel="stylesheet"
      href="https://streetview.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 } = StreetViewVN_Viewer;
      const { PhotoAdapter } = StreetViewVN_Viewer.adapter;
      const { VirtualTourPlugin, CompassPlugin } = StreetViewVN_Viewer.plugins;

      const BASE_PANORAMA = {
        baseUrl: "http://streetview.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: "http://streetview.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 streetview-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	http://www.streetview.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 streetview-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": "http://www.streetview.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 } = StreetViewVN_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 streetview 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

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];
 };

Streetview SDK

Description​

Usage​

Photo​

lang​

panorama​

adapter​

Plugins​

CompassPlugin​

PlanPlugin​

TrackPlugin​

VirtualTourPlugin​

Definitions​

CompassHotspot​

GpsPosition​

CssSize​

PlanHotspotStyle​

PlanLayer​

PlanHotspot​

VirtualTourNode​

TransitionOptions​

VirtualTourArrowStyle​

ArrowsPositionOptions​

MapOptions​

Description

Usage

Photo

`lang`

`panorama`

`adapter`

Plugins

CompassPlugin

PlanPlugin

TrackPlugin

VirtualTourPlugin

Definitions

CompassHotspot

GpsPosition

CssSize

PlanHotspotStyle

PlanLayer

PlanHotspot

VirtualTourNode

TransitionOptions

VirtualTourArrowStyle

ArrowsPositionOptions

MapOptions