react-image-mapper

react-image-mapper

React Component to highlight interactive zones in images

Demo & Examples

Live demo: coldiary.github.io/react-image-mapper

To build the example locally, run:

npm install
npm start

Then open localhost:8000 in a browser.

Installation

The easiest way to use react-image-mapper is to install it from NPM and include it in your own React build process (using Browserify, Webpack, etc).

You can also use the standalone build by including dist/react-image-mapper.js in your page. If you use this, make sure you have already included React, and it is available as a global variable.

npm install react-image-mapper --save

Usage

Import the component as you normally do, and add it wherever you like in your JSX views as below:

// ES5 require
var ImageMapper = require('react-image-mapper');

// ES6 import
import ImageMapper from 'react-image-mapper';

<ImageMapper src={IMAGE_URL} map={AREAS_MAP}/>

Properties

Props	type	Description	default
src	string	Image source url	required
map	string	Mapping description	{ name: generated, areas: [ ] } (see below)
fillColor	string	Fill color of the highlighted zone	rgba(255, 255, 255, 0.5)
strokeColor	string	Border color of the highlighted zone	rgba(0, 0, 0, 0.5)
lineWidth	number	Border thickness of the highlighted zone	1
width	number	Image width	Displayed width
height	number	Image height	Displayed height
active	bool	Enable/Disable highlighting	true
imgWidth	number	Original image width	null

Props callbacks	Called on	signature
onLoad	Image loading and canvas initialization completed	(): void
onMouseEnter	Hovering a zone in image	(area: obj, index: num, event): void
onMouseLeave	Leaving a zone in image	(area: obj, index: num, event): void
onMouseMove	Moving mouse on a zone in image	(area: obj, index: num, event): void
onClick	Click on a zone in image	(area: obj, index: num, event): void
onImageClick	Click outside of a zone in image	(event): void
onImageMouseMove	Moving mouse on the image itself	(event): void

Map is an object describing highlighted areas in the image.

Its structure is similar to the HTML syntax of mapping:

• map: (object) Object to describe highlighted zones
  • name: (string) Name of the map, used to bind to the image.
  • areas: (array) Array of area objects
    • area: (object) Shaped like below :

Property	type	Description
_id	string	Uniquely identify an area. Index in array is used if this value is not provided.
shape	string	Either rect, circle or poly
coords	array of number	Coordinates delimiting the zone according to the specified shape: rect: top-left-X,top-left-Y,bottom-right-X,bottom-right-Y circle: center-X,center-Y,radius poly: Every point in the polygon path as point-X,point-Y,...
href	string	Target link for a click in the zone (note that if you provide a onClick prop, href will be prevented)

When received from an event handler, an area is extended with the following properties:

Property	type	Description
scaledCoords	array of number	Scaled coordinates (see Dynamic Scaling below)
center	array of number	Coordinates positionning the center or centroid of the area: [X, Y]

Dynamic scaling

When a parent component updates the width prop on <ImageMapper>, the area coordinates also have to be scaled. This can be accomplied by specifying both the new width and a constant imgWidth. imgWidth is the width of the original image. <ImageMapper> will calculate the new coordinates for each area. For example:

/* assume that image is actually 1500px wide */

// this will be a 1:1 scale, areas will be 3x bigger than they should be
<ImageMapper width={500} />

// this will be the same 1:1 scale, same problem with areas being too big
<ImageMapper width={500} imgWidth={500} />

// this will scale the areas to 1/3rd, they will now fit the 500px image on the screen
<ImageMapper width={500} imgWidth={1500} />

Development (src, lib and the build process)

NOTE: The source code for the component is in src. A transpiled CommonJS version (generated with Babel) is available in lib for use with node.js, browserify and webpack. A UMD bundle is also built to dist, which can be included without the need for any build system.

To build, watch and serve the examples (which will also watch the component source), run npm start. If you just want to watch changes to src and rebuild lib, run npm run watch (this is useful if you are working with npm link).

Notes & Contributions

This a component is still a work in progress.

If you encounter a bug of some kind, feel free to report the issue.

If you'd like to improve this code or ask/advise for any improvement, feel free to comment it as well.

License

Distributed with an MIT License. See LICENSE.txt for more details

Copyright (c) 2017 Coldiary.