overlapmedia/imagemapper

Create image maps. View image maps. Interact with image maps by event listeners. Create your next Design Collaboration Tool?

imagemapper provides both drawing and view mode interaction capabilities letting you enable features of your image map adapted to the context of the user.

Instantiated as an editor it adds SVG drawing capability (rectangles, circles, ellipses and polygons) on top of your image to let you make image maps. Shapes could be frozen (freeze method) to disallow deleting, resizing and moving.
Instantiated as a view you can't draw new shapes or change imported shapes, but all other features (eg. importing and event handlers) are still available.

Getting started

With Node.js

$ npm install @overlapmedia/imagemapper

// Use imagemapper.editor or editor
import imagemapper, { editor, view } from '@overlapmedia/imagemapper';

// Editor
const myEditor = imagemapper.editor('editor', {
  width: 800,
  height: 400,
  selectModeHandler: () => console.log('Editor is now in select mode'),
  componentDrawnHandler: (component, componentId) => {
    // Disabling changes on new components. If you are making a design collaboration tool you probably want
    // to do this on components returned by the import function (meaning all existing components you are importing)
    // and let all other components drawn by the user respond to changes.
    component.freeze();

    console.log(
      `Disabled selecting, deleting, resizing and moving on component with id ${componentId}`,
    );
  },
});
myEditor.loadImage('image.svg', 700, 350);
myEditor.on('mouseup', (e) => console.log('mouseup event', e));
myEditor.polygon(); // Let user draw polygons

// View
const myView = view('view', {
  width: 800,
  height: 400,
  viewClickHandler: (e, id) => console.log('User clicked on', id),
});
myView.loadImage('image.png', 700, 350);
myView.import(
  '{"idCounter":4,"components":[{"id":"rect_1","type":"rect","data":{"x":66,"y":36,"width":253,"height":148}},{"id":"polygon_2","type":"polygon","data":[{"x":376,"y":172},{"x":498,"y":291},{"x":625,"y":174},{"x":500,"y":57}]},{"id":"polygon_3","type":"polygon","data":[{"x":54,"y":249},{"x":234,"y":246},{"x":236,"y":225},{"x":415,"y":270},{"x":237,"y":313},{"x":235,"y":294},{"x":54,"y":292}]}]}',
);

From browser

<script src="https://cdn.jsdelivr.net/gh/overlapmedia/imagemapper@1.0.13/dist/imagemapper.min.js"></script>
<script>
    const { editor, view } = imagemapper;
    const myEditor = editor('editor-id');
    myEditor.rect(); // Let user draw rectangles
</script>

With React

If you want to use imagemapper in a React app, these examples might get you started.

Demo

Try out the demo of imagemapper here.

Backlog

feat: Support rotating shapes
feat: Import data with SVG attrs format (ref. #1)

API Reference

Example

import imagemapper from '@overlapmedia/imagemapper';
const editor = imagemapper.editor('editor-id');
editor.polygon();

Example

import { editor, view } from '@overlapmedia/imagemapper';
const myEditor = editor('editor-id');
myEditor.polygon();

imagemapper
- static
  - .editor ⇒ Editor
  - .view ⇒ Editor
- inner
  - ~Editor(svgEl, [options], [style])
    - .loadImage(path, [width], [height]) ⇒ Editor
    - .setStyle(style) ⇒ Editor
    - .rect()
    - .circle()
    - .ellipse()
    - .polygon()
    - .selectMode()
    - .getComponentById(id) ⇒ Rectangle | Circle | Ellipse | Polygon
    - .selectComponent(component) ⇒ Rectangle | Circle | Ellipse | Polygon
    - .removeComponent(component) ⇒ Rectangle | Circle | Ellipse | Polygon
    - .on(eventTypes, handler) ⇒ Editor
    - .off(eventTypes, handler) ⇒ Editor
    - .import(data, [idInterceptor]) ⇒ Array.<(Rectangle|Circle|Ellipse|Polygon)>
    - .export([escape]) ⇒ string

imagemapper.editor ⇒ `Editor`

Editor

Kind: static constant of imagemapper

imagemapper.view ⇒ `Editor`

View

Kind: static constant of imagemapper
Returns: Editor - - an Editor constructor which does not add drawing capabilities

imagemapper~Editor(svgEl, [options], [style])

An Editor or View containing everything needed by the drawing/display board: DOM, event listeners, state and API functions.

Kind: inner method of imagemapper

Param	Type	Description
svgEl	`string` \| `SVGElement`	the id of the SVG element to be created or the SVG element itself if it's already made
[options]	`object`
[options.width]	`string`	if you let imagemapper create the SVGElement for you, you could specify width for it here
[options.height]	`string`	if you let imagemapper create the SVGElement for you, you could specify height for it here
[options.componentDrawnHandler]	`componentDrawnHandler`	function being called when finished drawing a valid component (eg. rectangle with width and height greater than 0 or polygon width at least three points), does not apply to importing
[options.selectModeHandler]	`selectModeHandler`	function being called when editor switches to select mode when eg. Esc keydown event or mousedown event on handle is causing it to leave draw mode
[options.viewClickHandler]	`viewClickHandler`	when using view this function will be called on click events from the shapes
[style]	`object`	see setStyle

~Editor(svgEl, [options], [style])
- .loadImage(path, [width], [height]) ⇒ Editor
- .setStyle(style) ⇒ Editor
- .rect()
- .circle()
- .ellipse()
- .polygon()
- .selectMode()
- .getComponentById(id) ⇒ Rectangle | Circle | Ellipse | Polygon
- .selectComponent(component) ⇒ Rectangle | Circle | Ellipse | Polygon
- .removeComponent(component) ⇒ Rectangle | Circle | Ellipse | Polygon
- .on(eventTypes, handler) ⇒ Editor
- .off(eventTypes, handler) ⇒ Editor
- .import(data, [idInterceptor]) ⇒ Array.<(Rectangle|Circle|Ellipse|Polygon)>
- .export([escape]) ⇒ string