Measure function

This tutorial will show you how to implement the Measure feature correctly. Measure is useful if you want to display objects in your zoom viewer and provide a scale to show visitors the exact dimensions of an object as they view it.

The plug-in does not support perspective correction. This means that measurements of scanned maps and diagrams will be accurate, but measurements of 3-dimensional objects will be less accurate.

The Measure plug-in is available in FSI Viewer version 18.06.25 and above.

How to enable Measure​

Adding the parameter plugins="Measure" provides an additional button/mouse mode that allows the user to measure distances and angles within the viewer by clicking and dragging. Please refer to the manual for a full list of available parameters.

You can either list the parameter for the plugin in the config XML or - as shown in this tutorial - directly in the fsi-viewer tag:

<fsi-viewer
  width="100%"
  height="100%"
  src="images/samples/auto/auto_01.jpg"
  skin="white"
  plugins="Resize, Fullscreen, Measure"
  measure_imageWidth="5.6"
  measure_Suffix=" m">
</fsi-viewer>

The parameter plugins="Measure" must be set, the corresponding parameters will then be listed as measure_ImageWidth, measure_Suffix, etc.

How to define Measure correctly - calculate ImageWidth​

To be able to use Measure, you need to define the scale correctly beforehand. The function needs the real width of the whole image to be able to measure the distance.

There are two ways to do this:

• you already know the total width of the image

• you only know the width of a specific part of the object in the image.

In this tutorial we will concentrate on the second case.

You can calculate the image width (w) as follows: w = real length / n *100.

For example, if we take the SUV as an example, we know that the car is 5 metres long. To apply this to the measure function, you need to do the following

1. add the measure function to the Viewer without any additional parameters

2. open the FSI Viewer and click on the Measure button

3. Now measure the part of the image where you know the width - in our example this is the width of the car. We know that the length is 5m, the measure tool displays the value n.

4. Calculate the value w for the ImageWidth parameter

Calculate ImageWidth​

• w = real length / n *100.

• The Measure plugin shows n = 89.3

• The real length L of the car is 5000 mm.

• ImageWidth: w = L / n *100 = 5000/ 89.3 * 100 = 5599

• If you want to display metres instead of mm, divide the ImageWidth by 1000. (ImageWidth ~ 5.6)

Set Measure as the initial mouse mode​

If you want Measure to be activated and displayed the moment the Viewer is initialised, you need to set the InitalMouseMode accordingly. The MouseMode ID for Measure mode is 100.

So the code needs to look like this:

<fsi-viewer
  width="100%"
  height="100%"
  src="images/samples/auto/auto_01.jpg"
  skin="white"
  plugins="Resize, Fullscreen, Measure"
  measure_imageWidth="5.6"
  measure_Suffix=" m"
  initialMouseMode="100">
</fsi-viewer>

How to set initial coordinates​

In some cases you may want to show a particular measured part from the beginning. The parameter for this is measure_initial.

This section shows you how to get the values for this parameter.

Step 1: Go to the browser and open the page that contains your viewer. Open the console using F12.

Step 2: You need to give your viewer an ID to refer to. In the example we have chosen id="measure".

Step 3: Type document.getElementById('measure').testAPIListenersStart().

This will start the API listener test (you can read more about the API here).

Step 4: Go to the viewer, click on the Measure button and measure the part you want as the initial measure.

Step 5: Select the [onMeasureEnd] listener in the console and open the details with the arrow next to Arguments.

Step 6: The values shown under 3: (the green selection in the picture below) are the values that need to be set in measure_Initial:

measure_Initial="0.23781512605042016, 0.6447761194029851, 0.23949579831932774, 0.9044776119402985". You can easily copy them from the console.

Example Code​

This is the code for the example:

measure_LineColor is used to change the colour of the measurement line.

<fsi-viewer
  id="measure"
  width="100%"
  height="100%"
  src="images/samples/auto/auto_01.jpg"
  skin="white"
  plugins="Resize, fullscreen, Measure"
  initialMouseMode="100"
  measure_ImageWidth="5.6"
  measure_Suffix=" m"
  measure_Initial="0.23781512605042016, 0.6447761194029851, 0.23949579831932774, 0.9044776119402985"
  measure_LineColor="a3ff00">
  <img
    src="http://localhost/fsi/server?type=image&source=images%2Fsamples%2Fauto%2Fauto_01.jpg"
    width="595"
    height="365"
    alt="Car" />
</fsi-viewer>