NeptuneLabs FSI Viewer JS User manual
FSI VIEWER
Let your website visitors have a closer look
User Manual
Version 2017
FSI Viewer JS
FSITouchZoom
FSIQuickZoom
FSIImageFlow
FSIShowcase JS
FSIPages JS
Developed by:
NeptuneLabs GmbH
Lagesche Str. 32
D-32657 Lemgo
Germany
© 2009-2017 NeptuneLabs. All rights reserved.
Last updated:
FSITouchZoom
FSIViewer JS
FSIPages JS
FSIImageFlow
FSIQuickZoom
Manual Revision
February 2017
17.02
17.02
17.02
17.02
17.02
055
All brands and product names are trademarks or registered trademarks of the respective producers.
FSI Viewer,FSIServer andNeptuneLabs are registered trademarks of NeptuneLabs GmbH, Germany.
Table of Contents
1 Introduction
8
2 FSI ViewerJS
10
2.1 How it works
11
2.2 Using FSIViewer JS
12
2.2.1 The Menu Bar
13
2.2.2 Mouse Modes
13
2.2.3 Additional Buttons
14
2.2.4 Using the navigator window
15
2.3 Index structure of FSI Viewer JS
15
2.4 Configuration
15
2.4.1 Using XML Configuration Files (*.xml)
15
2.4.2 Hierarchy of Configuration Parameters
17
2.4.3 Retrieving Parameters from FSIServer
19
2.4.4 Using Custom Language Files
19
2.4.5 Enabling the Debug Mode
20
2.5 FSI Viewer JS Parameters
20
2.5.1 Global Parameters for Hot Spots
39
2.5.2 <camera> Section
42
2.5.3 <virtualSpace> Section
49
2.5.4 <hotspots3d> Section
51
2.5.5 <video> Section
63
2.5.6 Plugin Parameters
67
2.6 Creating and using Spin Videos
70
2.7 Embedding the viewer at runtime via JavaScript
71
2.8 JavaScript Interface
73
2.8.1 Public Methods
73
2.8.2 Callbacks
81
3 FSI TouchZoom
88
3.1 Initializing FSI TouchZoom manually
89
3.2 FSI TouchZoom Parameters
90
3.3 Initializing FSI TouchZoom manually
93
3.4 JavaScript Interface
95
4 FSI QuickZoom
98
4.1 How it works
99
4.2 FSI QuickZoom Parameters
99
4.3 Initializing FSI QuickZoom manually
105
4.4 JavaScript Interface
106
5 FSI ImageFlow
110
5.1 How it works
111
5.2 FSIImageFlow Parameters
111
5.3 Embedding the viewer at runtime via JavaScript
126
5.4 JavaScript Interface
128
6 FSI Showcase JS
132
7 FSI Pages JS
134
7.1 How it works
134
7.2 Usage
134
7.2.1 Defining Image Collections
136
7.2.2 Aspect Ratio of the Pages
138
7.2.3 Printing Pages
138
7.2.4 Special URL Values
139
7.2.5 FSI Pages JS Presets in FSI Server Interface "Publish to Web"
140
7.3 FSI Pages JS Parameters
140
7.3.1 General Parameters
141
7.3.2 Layout/ Appearance Parameters
148
7.3.3 Link Parameters
160
7.3.4 Plug-in Parameters
165
7.4 JavaScript Interface
170
7.4.1 Public Methods
170
7.4.2 Callbacks
176
8 FSI Viewer
182
8.1 Compatibility and User System Requirements
182
8.2 Using FSIViewer
182
8.3 The Menu Bar
183
8.4 Mouse Modes
183
8.5 Additional Buttons
184
8.6 Using the navigator window
185
8.7 Keyboard Shortcuts
185
8.8 Index structure of FSI Viewer
186
8.8.1 Licensing FSIViewer
186
8.9 Integration into HTML Pages
187
8.9.1 Required HTML-Source Code
187
8.10 Configuration
188
8.10.1 Using XML Configuration Files (*.xml)
189
8.10.2 Using HTTP Queries
191
8.10.3 Hierarchy of Configuration Parameters
192
8.10.4 Default Configuration
193
8.10.5 Configuration Files
193
8.10.6 Passing Parameters by HTTP Query
194
8.10.7 Retrieving Parameters from Imaging Servers
194
8.10.8 Parameters
195
8.10.9 Applying Effects to Specific Images Only
218
8.10.10 Using Custom Language Files
226
8.11 Virtual 360° Presentations
226
8.11.1 Parameters for Virtual 360° Presentations
230
8.12 Debug Mode
236
8.12.1 Enabling the Debug Mode
236
8.12.2 Using the Debug Window
237
8.13 Automated Implementation of Images
238
8.14 Plug-ins
241
8.14.1 Deactivating Plug-ins
242
8.14.2 Defining Plug-in Parameters
243
8.14.3 Defining Plug-in Parameters dynamically
243
9 FSI Pages Add-on
246
9.1 Using FSIPages
246
9.2 FSI Pages Converter
247
9.3 Aspect Ratio of the Pages
247
9.4 Layout and Skins
248
9.5 Cropping
249
9.6 Defining Image Collections
250
9.7 Page Reading Order
252
9.8 Printing Pages
253
9.9 Saving Pages
254
9.10 Saving PDF or other document types
254
9.11 Searching in FSI Pages
256
9.12 Hyperlinks
258
9.13 Publishing PDF Documents with Links using FSI Pages Converter and FSI
Server
259
9.14 Providing XML page data to FSI Pages
259
9.15 Link Parameters and Hierarchy of Link Parameters
265
9.16 Relative and Absolute Links
267
9.17 Special URL Values
268
9.18 Modifying Link Values at Runtime
269
9.19 Page Overlays
270
9.20 FSI Pages Presets in FSI Server Interface "Publish to Web"
271
9.21 Event Notifications and Actions
272
9.22 Parameters to retrieve Image Collections
274
9.23 Basic Parameters
277
9.24 Parameters for the Front- and Backcover
284
9.25 Parameters defining Layout and Appearance
287
9.26 Parameters for Links on Pages
297
9.27 Parameters for FSI Pages Thumbnails
303
9.28 Parameters for Statistics
307
9.29 Advanced Parameters
309
10.1 FSI Pages mobile
328
10.1.1 Pages Mobile Parameters
329
10.1.2 Pages Mobile Plug-in Attribute targetdevice
331
11 FSI Showcase Add-on
332
11.1 Using FSI Showcase
332
11.2 Defining Image Lists
332
11.3 FSI Showcase Layout
335
11.4 Showcase Parameters
337
11.5 Basic Parameters
338
11.6 ImageList Parameters
344
11.7 Advanced Parameters
346
12 Plug-in Reference
362
12.1 AddThis
363
12.2 BackgroundImage
369
12.3 Chapters
371
12.4 ClockProgress
376
12.5 ColorAdjust
380
12.6 ContextMenu
383
12.7 CustomButton
385
12.8 Fullscreen
390
12.9 History
392
12.10 HotSpots
394
12.11 Imprint
408
12.12 JavaScript Bridge
411
12.13 LargeToolTips
424
12.14 Magnifier
429
12.15 MaxZoom
432
12.16 Measure
433
12.17 Mousemodes
442
12.18 MousemodeSelect
444
12.19 Music
446
12.20 NavExtension
449
12.21 Notepad
451
12.22 PagesLibrary
463
12.23 PagesMirror
467
12.24 PageSounds
469
12.25 PagesThumbBar
470
12.26 PrintSave
478
12.27 Resize
482
12.28 SelectFrame
484
12.29 ShoppingList
489
12.30 SoftwareCursor
495
12.31 StickyNotes
496
12.32 Synchronize
501
12.33 ZoomMeter
503
13 Appendix
506
A Escaping or URL-encoding parameter values
506
B HTML Tags available in FSI Viewer
506
C Example of a _default.xml file for FSIViewer Flash
507
D Example of an image specific FSI configuration file
507
E Example of a FSIViewer JS skin css file
508
13 Appendix
508
F Escaping or URL-encoding parameter values
508
G HTML Tags available in FSI Viewer
509
H Example of a custom skin CSS file
509
Index
515
NeptuneLabs - FSIViewer 8
1 Introduction
The JavaScript based viewers FSIViewer JS, FSITouchZoom, FSI QuickZoom,
FSIShowcase JS and FSIImageFlow bring outstanding zoom qualities to almost all
devices. They are highly customizable and work independently fromFSIViewer Flash.
FSI ViewerFlash and its Add-ons FSI Pages and FSI Showcase are based on Adobe
Flash and have been designed to display high resolution images on the internet
requiring low bandwidth only.
FSIServer is the basis of all viewers which request the image data from it. By using
FSIServer, only one high resolution source image is required for each image to be
displayed.
Thank you for using NeptuneLabs software!
www.neptunelabs.com
: Online Resources for FSI Viewer
Visit
www.neptunelabs.com
for software updates, regularly updated samples, tutorials
and downloads.
1 Introduction
2 FSI ViewerJS
FSI Viewer JS is a JavaScript based tool to display 2D image zoom and 360° Object spins
on desktop computers and mobile devices. Depending on the device capabilities it offers
in place zoom or pinch zoom support. FSIViewer JS also supports optional multiple axis
spin.
Using an optional video, the rotation of the 360° object can be displayed extremely
smooth on devices that support video capturing.
Optional hot spots with HTML content can be added by providing 3D coordinates (x,y,z)
in millimeters.
Imaging Servers
FSI products covered by this manual can at present securely be run with FSI Server
from version 2016.
Supported devices
liOS 4 or higher
lAndroid 4.x based devices
lWindows Phone 8 and Windows RT devices
lWindows 8 with touch enabled browsers
lMouse zoom: desktop or laptop computers &all major browsers
Usage
I) add the fsiviewer.js script to the head of your document:
Adding the script
<head>
[…]
//adding the fsiviewer.js script
<script src="viewer/applications/viewer/js/fsiviewer.js"
type="text/javascript"></script>
</head>
II) Add a <fsi-viewer> tag to the part of your document body where the zoom and/or
the 360° product spin should be displayed. Add the desired dimension and the
imagesource/ directory to it:
2 FSI ViewerJS
NeptuneLabs - FSIViewer 10
2 FSI ViewerJS
11 NeptuneLabs - FSIViewer
Integrate FSI Viewer JS
<body>
[…]
<fsi-viewer width="500" height="600" src="/images/foo.tiff">
//here you can place the fallback content in case the browser
// cannot display the viewer, e,g,:
<b>Sorry</b>, your browser is not capable of running FSI Viewer
JS
</fsi-viewer>
Parameters are added to the <fsi-viewer> tag. Note that you can as well use FSI
Viewer configuration files (required when using hot spots):
Adding Parameters to the viewer
<head>
[…]
//adding the fsiviewer.js script
<script src="js/fsiviewer.js" type="text/javascript"></script>
</head>
<body>
[…]
//Adding parameters directly to the tag:
<fsi-viewer width="500" height="600" src="/images/sample.jpg"
debug="true" skin="silver">
</fsi-viewer>
//Example with using a FSIViewer configuration file:
<fsi-viewer width="500" height="600" src="/images/sample.jpg"
cfg="sample/sample_configuration">
</fsi-viewer>
2.1 How it works
The script uses the given <fsi-viewer> tag, which is similar to an <img> tag, to
display a single image zoom and/or 360° object spin.
If a video has been defined, the script captures video frames on start to provide an
ultra smooth rotation.
Without a video (or on devices not supporting video capturing) a fixed number of
images from different viewing angels will be used to display the object spin.
The user can drag the image left and right to spin and zoom in/out either using
pinch zoom or by clicking on the object.
Note on Internet Explorer:
In order to make FSI Viewer JS work, Internet Explorer must run in IE8 quirks, IE9 or
higher quirks or standards mode. You can ensure that by adding an X- UA-
Compatible meta tag to the head section of your web page, for example:
<meta http-equiv="X-UA-Compatible" content="IE=Edge">
2.2 Using FSIViewer JS
33,3%
Viewer
360°
FSI Viewer JSis navigated
by the menu bar (here
seen below the image)
and by using the mouse
directly on the image. For
example, you can select
a section of the image
you want to magnify.
The mouse functions are
determined by the
corresponding buttons
on the menu bar (zoom,
pan, rotate, etc.).
The optional small
navigator window
(bottom right) displays the position of the image section currently viewed.
2 FSI ViewerJS
NeptuneLabs - FSIViewer 12
2 FSI ViewerJS
13 NeptuneLabs - FSIViewer
2.2.1 The Menu Bar
100%
Viewer
360°
The menu bar might look different depending on skins or
additional plugins.
Main Functions
Back to Initial View.
Undoes zoom, pan and rotation and restores the initial view.
(identical with pressing space bar)
Zoom In
Zoom Out
2.2.2 Mouse Modes
The
→ Mousemodes
or
→ MousemodeSelect
plug-in is required to display the
following mouse mode buttons.
Mouse - Zoom In
Choose this function to enlarge segments using the mouse. Click on
the image and drag the frame over the desired segment.
Alternatively you can click on the image, without marking a
segment. The image will then be magnified in steps. To zoom out in
steps, hold down the CTRL-key and click on the image.
Mouse - Pan
Choose this function to pan the image using the mouse. Click on the
image and drag in the desired direction. To return to the original
view, hold down the CTRL-key and click on the image.
Mouse - Turn
Choose this function to rotate the image around the z-axis. Click on
the image and drag in whatever direction you want to turn the
object (to the right or the left). To reset the rotation, hold down
the CTRL-key and click on the image.
360°
Mouse - Rotate (only for 360° presentations)
Choose this function to rotate the object around the y-axis or the
x-axis ifavailable. Click on the image and drag to the left or to the
right. Move the mouse up or down to rotate the object around the
x-axis. To reset rotation, hold down the CTRL-key and click on the
image.
2.2.3 Additional Buttons
Hide /Display menu
Displays or hides the user interface.
Viewer
Information
Displays information about the viewer (optional, can be hidden by
altering the skin CSS)
2 FSI ViewerJS
NeptuneLabs - FSIViewer 14
2 FSI ViewerJS
15 NeptuneLabs - FSIViewer
2.2.4 Using the navigator window
15%
In the navigator window you can see a miniature presentation
of the entire image. The segment which is currently viewed is
framed. In the navigator window you can change the current
segment either by dragging the frame or by clicking on the
desired area of the image.
2.3 Index structure of FSI Viewer JS
The index structure of the JS viewers as found in WEBAPPS/fsi/viewer/:
Directory Content Description
applications contains the .js scripts for the according viewers
config contains the configuration files
languages User interface language files
plugins FSI Plug-ins extending FSI Viewer at runtime
skins FSI Skins containing the visible parts of the user interface
Please Note: You need to make sure that your web server properly serves files with
the following extensions: *.js, *.xml
2.4 Configuration
2.4.1 Using XML Configuration Files (*.xml)
FSI Viewer JS uses XML configuration files which can easily be edited with any
text editor.
The default configuration file "_ default.xml" - which is located in
WEBAPPS/fsi/viewer/ is the most important XML configuration file and will
always be evaluated first.
To use FSI Viewer with additional configuration files you have to place the file in
the WEBAPPS/fsi/viewer/config/ folder and provide the name of the
configuration file using the "cfg" parameter in the code:
Using FSI Viewer Configuration Files
<head>
[…]
//adding the fsiviewer.js script
<script src="js/fsiviewer.js"
type="text/javascript"></script>
</head>
<body>
[…]
//Example with using a FSI Viewer configuration file:
<fsi-viewer width="500" height="600"
src="/images/sample.jpg" cfg="sample/sample_configuration">
</fsi-viewer>
Configuration files are structured into configuration groups (XML nodes)
containing parameter names and values. Only parameters in these groups will
be recognized by FSI Viewer. Configuration files do not need to contain all
groups though. Each parameter has to be provided as an individual XML child
node of a group where the node name is the parameter name and the
parameter value needs to be provided as "value" attribute of the node.
Structure of XML configuration files
<fsi_parameter>
<image>
<parameter value="" />
</image>
<plugins>
<parameter value="" />
</plugins>
<options>
<parameter value="" />
</options>
</fsi_parameter>
2 FSI ViewerJS
NeptuneLabs - FSIViewer 16
2 FSI ViewerJS
17 NeptuneLabs - FSIViewer
Simple XML configuration file
<fsi_parameter>
<image>
<path value="samples/Watch.jpg" />
</image>
<options>
<skin value="silver" /><
debug value="1" />
</options>
</fsi_parameter>
Please keep in mind the following rules when using XML configuration files:
lattribute values must be provided in double quotes
lthe last occurrence of a given parameter will be used
lconfiguration files might be cached by your browser, so that changes in
these files require flushing the browser cache. This does not apply
when using the debug mode.
lmake sure to save configuration files in UTF- 8 format if your
configuration file contains language specific diacritics, Japanese
characters and alike
You can comment on or disable sections of an XML configuration file using the
usual XML comment syntax:
Comments and disabling parameters temporarily
<image>
<!—- This is a comment -->
<path value="image.tif" />
<!-- The following section will be ignored -->
<!--
<path value="anotherimage.tif" />
-->
</image>
2.4.2 Hierarchy of Configuration Parameters
As explained before parameters can be provided in two different ways:
1. The default configuration file "_ default.xml" - located in
WEBAPPS/fsi/viewer/ - will always be evaluated first
2. You can store image specific parameters in additional *.xml files in
WEBAPPS/fsi/viewer/config/
Parameters specified in multiple ways – for example in the default configuration
and by custom configuration files– will be evaluated in the following way:
lParameters defined in configuration files override parameters
defined in the default configuration file "_default.xml".
The list below shows the hierarchy resulting from the sequential
evaluation of the different configuration methods:
Configuration Hierarchy
1. Configuration file (*.xml)
2. Default configuration file (_default.xml)
Choosing the adequate Configuration Method
So far you learned that FSI Viewer JS can be configured by any
combination of:
lThe default configuration file (_default.xml)
lAdditional configuration files (*.xml)
These configuration options are not only alternate methods. Combining
these methods offers the possibility to provide configuration parameters
as easily as possible and as dynamically as required. The following
considerations might be helpful when deciding which method to choose for
a certain parameter.
Default Configuration
You can easily change global parameters that apply to all FSI Viewer instances
by editing a single file. This is therefore the recommended configuration
method for:
General configuration options like:
lSkin
lLanguage
lMenuAlign, AnimationSpeed and alike
Configuration Files
Separate configuration files should be used for parameters specific to a group
of images or a specific way to display images. You might for example want to
setup individual configuration files for different types of FSI Viewer JSinstances,
like "small_no_interface. xml", "large_with_hotspots.xml" as an example.
2 FSI ViewerJS
NeptuneLabs - FSIViewer 18
2 FSI ViewerJS
19 NeptuneLabs - FSIViewer
Usually you don‘t need to create a configuration file for individual images, as you
can specify the image path or other unique parameters dynamically in the code.
2.4.3 Retrieving Parameters from FSIServer
FSI Viewer JS is capable of retrieving image specific parameters from FSI Server
dynamically. This way you do not need to define these parameters explicitly.
The list below shows some typical parameters that can be retrieved from FSI
Server automatically:
lImageWidth
lImageHeight
lImageTilesX
lImageTilesY
lSceneSets
lImage Collections
lHyperlinks
lHotspots
In which case will these values be retrieved automatically?
FSI ViewerJS tries to retrieve the parameters ImageWidth and ImageHeight
from the server if one of these values has not been defined manually. If the
server delivers additional parameters (e.g. ImageTilesX, ImageTilesY) these
parameters will only have an effect if they have not been defined manually.
2.4.4 Using Custom Language Files
In case you want to edit tool tips for existing languages or add support for
additional languages you can edit or create language files in the subdirectory
"/languages" of your FSI Viewer setup directory.
Each language file contains a list of phrases used in FSI ViewerJS user
interface.The language files are XML files and need to be saved in UTF-8 format.
The attribute "id" specifies the context of each phrase. Please note that you
need to use XML entities for characters not allowed in XML files, like e.g.
& for "&"
< for "<"
> for ">"
" for "
' for ‚
You can use basic HTML-tags to applytext formatting to the tool tips.
Excerpt from a language file
<Data language="english" color="000000" font="_ sans"
offsetTop="0" offsetLeft="0"
offsetWidth="0" offsetHeight="0">
<tip id="ZoomOut"><b>Zoom Out</b><br/>Click to
decrease magnification</tip>
<tip id="ZoomIn"><b>Zoom In</b><br/>
Click to increase
magnification</tip>
<tip id="Downloading Data">Downloading:</tip>
[...]
</Data>
You can duplicate existing language files or create new files as needed.
To use custom language files, please use the "language" parameter and set
the parameter value to the filename without the ".xml" extension.
2.4.5 Enabling the Debug Mode
The debug mode can be enabled or disabled by passing the "Debug" parameter
either in the code snip or in an XML configuration file.
Please use "debug=1" or "debug=true" to enable the debug mode and
"debug=0" (or omit the debug parameter) to disable the debug mode. To
disable the debug mode permanently you can safely delete the "/debug"
directory of your FSI setup directory.
Example:
If FSI Viewer JS does not work or look as expected in an HTML page you can
quickly debug FSI Viewer as follows:
lOpen the HTMLpage containg FSIViewer JS
lOpen the"Inspect Element" feature of your browser
lin the "Console" part you can now check if everything is implemented
and loaded correctly
2.5 FSI Viewer JS Parameters
You can optionally modify the way FSI Viewer JS works by passing parameters to
the script. To do so, pass an object containing the parameters and value as an
2 FSI ViewerJS
NeptuneLabs - FSIViewer 20
This manual suits for next models
5
Table of contents
