@grapecity/gcimageviewer

GrapeCity Documents Image Viewer

A JavaScript Image viewer and editor that comes with GrapeCity Documents for Imaging.

GrapeCity Documents Image Viewer (GcDocs Image Viewer, GcImageViewer) is a fast modern JavaScript based image viewer and editor that runs in all major browsers. The viewer can be used as a cross platform solution to view or modify images on Windows, MAC, Linux, iOS and Android devices. GcImageViewer is included in GrapeCity Documents for Image (GcImaging), a feature-rich cross-platform Image API library for .NET.

GcImageViewer provides a rich client side JavaScript object model, see docs/index.html for the client API documentation.

Product highlights:

• Works in all modern browsers including IE11, Edge, Chrome, FireFox, Opera, Safari.
• Works with pure JavaScript and frameworks such as Angular, Vue, ASP.NET Core, ASP.NET MVC, HTML5, React and Preact.
• Allows you to extend the viewer behavior and add new functionality using plug-ins.
• Provides a client API for creating and modifying image data.
• Supports raster image formats JPEG, PNG, WEBP, TIFF, GIF, BMP, ICO, and vector SVG format.
• ...and more.

See it in action

• Go to GrapeCity Documents Image Viewer demos to explore the various features of GcImageViewer. The demo site allows you to modify the demo code and immediately see the effect of your changes.
• The GrapeCity Documents for Imaging demos can optionally use GcImageViewer to show the sample images (to opt in or out of using GcImageViewer, click the blue "i(nformation)" icon in the top right corner of the image preview panel).

Latest changes

[1.0.3] - 20-Jan-2023

Added

• Added the ability to select/copy/search text content in SVG images. (DOC-4952)

[1.0.1] - 21-Dec-2022

Fixed

• [iOS] The flip vertical icon is incorrect. (DOC-4867)
• Cannot load a TIFF or GIF image when ImageFilters plugin is added without sidebar panel. (DOC-4967)
• The zoom toolbar buttons overlap the zoom input box. (DOC-4991)
• SVG image is clipped when its viewBox has a negative offset. (DOC-4990)

[1.0.0] - 06-Dec-2022

Added

• Added isAnimationStarted property: gets a value indicating whether the image animation has started.

  // Example: toggle image animation:
  const viewer = GcImageViewer.findControl("#root");
  if(viewer.isAnimationStarted) {
    viewer.stopAnimation();
  } else {
    viewer.startAnimation();
  }

• [Page Tools plugin] [Crop dialog] Added the ability to select a crop area using the selection UI.
• Implemented standard licensing. (DOC-4586)
• Added image filters plugin. (DOC-4585)
• Added the ability to provide own image filter using the filters property.

  // Example: create Image Filters plugin:
  const imageFiltersPlugin = new ImageFiltersPlugin();
  // Remove the default image filters, except for the "Invert" filter:
  const filters = imageFiltersPlugin.filters;
  for (const filterName in filters) {
    if(filterName === "invert")
      continue;
    delete filters[filterName];
  }
  // Add custom Image Filter:
  filters["lemon-effect"] = {
    filterId = "lemon-effect",
    toolbarKey: "lemon-effect",
    title: "Apply Custom Lemon effect",
    text: "Apply Lemon effect",
    action: function(imageData) {
      for (i = 0; i < imageData.data.length; i += 4) {
        imageData.data[i + 1] = imageData.data[i] + 45; // increase green component
      }
      return imageData;
    }
  };
  // Register Image Filters plugin:
  viewer.addPlugin(imageFiltersPlugin);

• Added PageToolsPlugin, which replaces the Rotation plugin. This plugin provides crop/resize dialog and functionality.

  // Example:
  viewer.addPlugin(new PageToolsPlugin());

• Added maxImageSize option, which replaces the maxCanvasPixels option. Use maxImageSize to limit the image size when editing an image.

  // Example:
  var viewer = new GcImageViewer("#root", { maxImageSize: { width: 1080, height: 1350 } });

• Added vertical flip tool. (DOC-4582)
• Added close() method.
• Added the ability to disable individual undo operations using the skipCommands setting.
  Available command names are: "Open", "Close", "FrameIndex", "Zoom", "Rotation", "Flip", "StartAnimation", "StopAnimation".
  Note that the "Open"/"Close" and "StartAnimation"/"StopAnimation" commands are paired - if one command is skipped, the other command will also be skipped.

  // Example:
  var viewer = new GcImageViewer("#root", { undo: { skipCommands: ["Open", "Close", "Zoom"] } });

• Added findPlugin method - finds a viewer plugin by its id.

  // Example:
  var pluginRotate = viewer.findPlugin("rotation");

• Added command based undo state storage. (DOC-4583)

  // Example 1: disable undo storage.
  var viewer = new GcImageViewer("#root", { undo: false });

  // Example 2: Limit the maximum number of undo levels to 5.
  var viewer = new GcImageViewer("#root", { undo: { maxLevels: 5 } });

  // Example 3: Create an undoable custom command that changes the opacity of the main viewer element.
  var viewer = new GcImageViewer("#root");
  function CustomOpacityCommand(opacity) {
      if(opacity !== undefined) {
      this.opacity = opacity;
    }
  }
  CustomOpacityCommand.prototype = {
    opacity: "0.5",
    prevOpacity: "",
    execute: function(viewer) {
      return new Promise((resolve) => {
        this.prevOpacity = viewer.hostElement.style.opacity;                                
        viewer.hostElement.style.opacity = this.opacity;
        resolve();
      })
    },
    undo: function(viewer) {
      return new Promise((resolve)=>{
        viewer.hostElement.style.opacity = this.prevOpacity;
        resolve();
      })
    }
  };
  // Open image:
  await viewer.open(https://example.com/download?file=images/image.jpg);
  // Clear undo storage:
  viewer.clearUndo();
  // Execute custom command:
  await viewer.executeCommand(new CustomOpacityCommand(0.2))
  // Undo to previous state:
  await viewer.undo();
  // Redo to next state:
  await viewer.redo();

Fixed

• Incorrect SVG image size when the SVG contains elements that are larger than the outer "SVG" element. (DOC-4726)
• Zoom to cursor using mouse wheel does not work for SVG images. (DOC-4728)
• The frameIndex is incorrect when switching from BMP to TIFF using the undo button. (DOC-4637)
• [API reference] Added missing descriptions. (DOC-4681, DOC-4639)

See CHANGELOG.​md for previous release notes.

Installing and using the viewer

Installing from npmjs:

npm install @grapecity/gcimageviewer

Installing from the zip archive:

The following viewer distribution files are located in the zip archive:

• build/README.md (this file)
• build/CHANGELOG.md
• build/index.html
• build/gcimageviewer.js
• build/plugins/ (optional) Plugins
• build/themes/ (optional) Theme files
• build/typings/ (optional) Type definitions

Copy those files to an appropriate location accessible from the web page where the viewer will live, e.g. if the files are put in the directory where the web page is, the following HTML can be used to show the viewer:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <meta name="theme-color" content="#000000" />
    <title>GrapeCity Documents Image Viewer Demo</title>
    <script src="gcimageviewer.js"></script>
    <script src="plugins/rotation.js"></script>
    <script>
      function loadImageViewer(selector) {
        var viewer = new GcImageViewer(selector);
        viewer.addPlugin(new RotationPlugin());
      }
    </script>	
  </head>
  <body onload="loadImageViewer('#root')">
    <div id="root"></div>
  </body>
</html>

---

The End.