@3dweb/360javascriptviewer/typings/JavascriptViewer.d.ts

A 360 javascript viewer working with images

import { Slot } from 'ts-event-bus';

export class JavascriptViewer {
  /**
   * Create an instance of the viewer.
   * There are multiple instances possible on a page
   * @param options
   */
  constructor(options: options);

  /**
   * Use this to register events.
   * @return IEvents
   */
  events(): IEvents;

  /**
   * Start the presentation, loading all images and replace the main image with a 360 presentation
   * @async
   * @return boolean
   * @throws string
   */
  start(): Promise<boolean>;

  /**
   * Destroys the presentation and returns to previous state
   * @async
   * @return boolean
   * @throws string
   */
  destroy(): Promise<boolean>;

  /**
   * Set the desired rotation and the 360 model is rotating to it.
   * @async
   * @param degree
   * @return IResponse
   * @throws string
   */
  rotateDegrees(degree: number): Promise<IResponse>;

  /**
   * Rotate to a certain degree. Frame nr 1 is 0 degrees.
   * @param targetDegree
   * @param shortestWay
   * @param useEasing
   * @return IResponse
   * @throws string
   */
  rotateToDegree(targetDegree: number, shortestWay?: boolean, useEasing?: boolean): Promise<IResponse>;

  /**
   * Rotate to a certain degree. Frame nr 1 is 0 degrees.
   * @param frame
   * @param shortestWay
   * @param useEasing
   * @return IResponse
   * @throws string
   */
  rotateToFrame(frame: number, shortestWay?: boolean, useEasing?: boolean): Promise<IResponse>;

  /**
   * Set the current speed of rotating for the viewer instance
   * @param speed
   */
  setSpeed(speed: number): void;

  /**
   * Set the current inertia of the viewer
   * Set the current inertia for the viewer instance
   * @param inertia
   */
  setInertia(inertia: number): void;

  /**
   * Change the current presentation created by 3dweb.io
   * @param id
   */
  setId(id: number): Promise<boolean>;

  /**
   * Resets the zoom
   */
  resetZoom(): Promise<void>

  /**
   * Zoom to given location.
   * x and y are percentages from the middle 0-1 and -1-0
   */
  zoomTo(factor: number, x: number, y: number): Promise<void>

  /**
   * Checks if the presentation is zoomed
   */
  isZoomedIn(): boolean
}

export type Optional<T> = {
  [P in keyof T]?: T[P];
};

export type options = Optional<IOptions>;

export interface IResponse {
  currentDegree: number;
}

export interface IOptions {

  /**
   * ID of the presentation created by 3dweb.io
   */
  id?: string;

  /**
   * ID of the image which is the base for all the frames
   * default is jsv-image
   */
  mainImageId?: string;

  /**
   * ID of the div where the presentation runs in
   * Default is jsv-holder
   */
  mainHolderId?: string;

  /**
   * URl of the first image, doesn't have to be in the document.
   * Default is empty
   */
  mainImageUrl?: string;

  /**
   * Amount of frames in the presentation, more images means smoother rotations
   * but also more heavier for the browser
   * default is 72
   */
  totalFrames?: number;

  /**
   * After loading the presentation this is the first frame visible
   * Default is 1
   */
  firstImageNumber?: number;

  /**
   * Invert the rotation direction when dragging
   * Default is false
   */
  reverse?: boolean;

  /**
   * Speed of rotating -199 to 100
   * Default is 80
   */
  speed?: number;

  /**
   * Delay when stop dragging
   * Default is 20
   */
  inertia?: number;

  /**
   * Disable the build in progress bar, use this when you have
   * implemented your own loader or don't like this one.
   * Default is true
   */
  defaultProgressBar?: boolean;

  /**
   * Change the color of the progress bar, can be hex of rgb
   * Default is rgb(0, 0, 0)
   */
  defaultProgressBarColor?: string;

  /**
   * Change the background color of the progress bar, can be hex or rgb
   * Default is rgba(255, 255, 255, 0.5)
   */
  defaultProgressBarBackgroundColor?: string;

  /**
   * Change the height of the progress bar, can be any css value for height
   * Default is '5px'
   */
  defaultProgressBarHeight?: string;

  /**
   * Format for determining the filenames of the frames
   * {filename}_xx.{extension} is the default
   * ipod_x.jpg => ipod_1.jpg
   * ipod_xx.jpg => ipod_01.jpg
   * https://other.cdn/images/ipod_xx.jpg => https://other.cdn/images/ipod_01.jpg
   */
  imageUrlFormat?: string;

  /**
   * Load all image urls into the viewer. Total frames will be overwritten
   */
  imageUrls?: string[];

  /**
   * Add a class to all the images used in the presentation, separate multiple classes with a space.
   * Default is empty
   */
  extraImageClass?: string;

  /**
   * Add an alt text to the images, all images will have the same alt text.
   * Default is empty and no alt text is added
   */
  imageAltText?: string;

  /**
   * Use this setting in combination with imageUrlFormat.
   * startFrameNo: 4 => first file is ipod_04.jpg
   * Default is 1
   */
  startFrameNo?: number;

  /**
   * Use this setting for rotating the view at start. Rotation stops when user drags the model
   * or another animation method is called
   * startRotation: 0 => No Rotation, 1 => Rotate once, 2 => Rotate twice
   * Default is 0
   */
  autoRotate?: number;

  /**
   * Use this setting for changing the speed of the auto rotating. -199 to 100
   * Default is speed of viewer
   */
  autoRotateSpeed?: number;

  /**
   * Use this setting for changing the direction of the auto rotating.
   * Default is false
   */
  autoRotateReverse?: boolean;

  /**
   * Use this setting for enabling click and pinch events on images
   * Default is false
   */
  enableImageEvents?: boolean;

  /**
   * Fires changeImage event in rotation. Keep track what your user is watching.
   * Could be CPU heavy
   * Default is false
   */
  enableChangeImageEvent?: boolean;

  /**
   * Use this setting for enabling zoom functions.
   * Default is false
   */
  zoom?: boolean;

  /**
   * If zoom is enabled this is the max zoom factor.
   * Default is 2
   */
  zoomMax?: number;

  /**
   * Change the speed of zooming with the mousewheel.
   * Default is 50
   */
  zoomWheelSpeed?: number;

  /**
   * Blocks repeating images after reaching last image.
   * Default is false
   */
  stopAtEdges?: boolean;

  /**
   * Change the cursors for the presentation
   */
  cursorConfig?: ICursorConfig;

  /**
   * Configure the notifications
   */
  notificationConfig?: INotificationConfig;

  /**
   * Set the query params height and width for use with an image resizer.
   */
  autoCDNResizer?: boolean;

  /**
   * Configure the image resizer
   */
  autoCDNResizerConfig?: IAutoCDNResizerConfig;

  /**
   * License to remove powered by logo
   * Default is empty
   */
  license?: string;
}

/**
 * Object for getting the loading progress
 */
export interface IProgress {
  totalImages: number;
  currentImage: number;
  percentage: number;
  image: IImage;
}

export interface IHandle {
  invocations: number;
}

export interface IEvents {
  loadImage: Slot<IProgress>;
  started: Slot<boolean>;
  startDragging: Slot<IHandle>;
  changeImage: Slot<IStatus>;
  endAutoRotate: Slot<IStatus>;
  click: Slot<IClick>;
  pinch: Slot<IPinch>;
  scroll: Slot<IScroll>;
  doubleClick: Slot<IClick>;
}

export interface IImage {
  id: string;
  src: string;
  sequence: number;
}

export interface IStatus {
  currentDegree: number;
  currentImage: IImage;
  completed: boolean;
}

export interface IClick extends IStatus {
  originalEvent: TouchEvent | MouseEvent;
}

export interface IPinch extends IStatus {
  originalEvent: TouchEvent,
  scale: number
}

export interface IScroll extends IStatus {
  originalEvent: Event;
}

interface ICursorConfig {
  default: string,
  drag: string,
  zoomIn: string,
  zoomOut: string,
  pan: string
}

interface INotificationConfig {
  dragToRotate: {

    /**
     * If you want to show a custom image as notification
     */
    imageUrl?: string,

    /**
     * Show the default notification when starting to rotate
     * Default is true
     */
    showStartToRotateDefaultNotification?: boolean,

    /**
     * Override the default text for the notification for any language
     */
    languages?: ITranslation[],

    /**
     * Set the background color for the notification, hex or rgba
     * Default is rgba(0,0,0,0.20)
     */
    mainColor?: string,

    /**
     * Set the text color for the notification, hex or rgba
     * Default is rgba(243,237,237,0.80)
     */
    textColor?: string
  };
}

interface ITranslation {
  language: string;
  text: string;
}

interface IAutoCDNResizerConfig {
  useWidth?: boolean,
  useHeight?: boolean,
  scaleWithZoomMax?: boolean,
  extraParams?: Record<string, string>
}