PTViewer: applett per visualizzare le immagini panoramiche

PTViewer è un visualizzatore di immagini panoramiche gratuito e aperto. E' scritto in linguaggio Java (v.1.0.4) e dovrebbe girare in qualsiasi browser abilitato a java. Dalla versione 1.4 c'è una applicazione Java eseguibile senza browser su installazioni Java 1.1.

ecco le sue caratteristiche principali:

PTViewer gestisce immagini panoramiche equirettangolari che devono coprire tutti i 360* gradi orizzontali. La copertura verticale può essere qualsiasi valore te 0° e 180°. Nella proiezione equirettangolare, sia l'asse verticale che quello orizzontale sono proporzionali all'angolo visivo. Invece un panorama seferico ha un rapporto esatto di 2:1.

<APPLET archive=ptviewer.jar code=ptviewer.class width=320 height=200>
<PARAM name=virtual   value="pano.JPG">
</APPLET>

virtual	E' il nome dell'immagine panoramica. In alternativa, un panorama da una lista specificata usando il tag pano 0/1/2, puo' essere caricato usando come nome virtual 'ptviewer:Number' . Es: 'ptviewer:3' carica il panorama con il nr. di lista 3. si veda il capitolo successivo per maggiori informazioni
roi0/1/2	Lista delle sezioni di immagine ad alta risolizione da inserire nel panorama. Per la sintassi e i dettagli consultare il capitolo più avanti.
tilt	Angolo di elevazione iniziale (da -90 a +90, preimpostato a 0)
pan	Angolo di rotazione iniziale (da - 180 a + 180, preimpostato a 0)
panmax	Angolo di rotazione massimo (da - 180 a + 180, preimpostato a 0)
panmin	Angolo di rotazione minimo (da - 180 a + 180, preimpostato a 0)
fov	Campo visivo orizzontale iniziale. (da 12 a + 165, preimpostato a 70)
fovmax	Campo visivo massimo (preimpostato a 165)
fovmin	Campo visivo minimo (preimpostato a 12)
tiltmin	Angolo di elevazione minimo (da -90 a 0, predefinito a -90 per i pano sferici, o al campo visivo inferiore per i pano cilindirici)
tiltmax	Angolo di elevazione massimo (da 90 a 0, predefinito a 90 per i pano sferici, o al campo visivo superiore per i pano cilindirici)
wait	nome dell'immagine gif o jpeg da visualizzare durante lo scaricamento. Specifica il percorso relativo al documento html. L'immagine viene mostrata centrata nella finestra dell'applet.
waittime	Tempo minimo per mostrare l'immagine di attesa, in millisecondi (predefinito a 0). Questo è utile se viene usata una immagine gif animata; l'animazione dovrebbe finire prima della visualizzazione del panorama.
auto	Angolo di rotazione automatica (da -360 a +360, predefinita a 0) l'angolo di rotazione viene incrementato di questa quantità per ogni frame. Si possono specificare gradi o valori frazionali.
hotspot 0,1,2...	Modo alternativo di impostare gli hotspot, si veda il capitolo piu' avanti
shotspot 0,1,2...	Hotspot statici, si veda il capitolo più avanti
maxarray	Dimensione massima per il vettore lineare sul computer (predefinito a 524288 per Netscape). vedere le note sulle immagini grandi.
frame	un'immagine che viene sovrapposta alla finestra del panorama. Può essere una GIF o una JPEG. Viene inserita nell'applet allineata in basso a destra. Si veda l'esempio in contrlos.html per un esempio.
mousehs	Nome di una funzione javascript definita dall'utente che viene chiamata ogni volta che il mouse entra o esce da un hotspot. Esempi e note piu avanti in queste pagine.
getnew	Nome di una funzione javascript definita dall'utente che viene chiamata ogni volta che cambia la vista (pan, tilt o fov cambiano). Esempi e note piu avanti in queste pagine.
bar_x	Coordinata x dell'angolo a sinistra in alto della barra di caricamento (predefinita: width/4)
bar_y	Coordinata y dell'angolo a sinistra in alto della barra di caricamento (predefinita: height*3/4)
bar_width	Larghezza della barra di caricamento (predefinita: width/2)
bar_height	Altezza della barra di caricamento (predefinita: 10 pixel)
barcolor	Colore della barra di caricamento (predefinito: grigio scuro)
view_width	Larghezza del visualizzatore in pixel. Predefinito alla larghezza della finestra dell'applet.
view_height	Altezza del visualizzatore in pixel. Predefinito all'altezza della finestra dell'applet.
view_x	Coordinata x dell'angolo in alto a sinistra del visualizzatore (predefinito: 0)
view_y	Coordinata y dell'angolo in alto a sinistra del visualizzatore (predefinito: 0)
pano 0,1,2,3	Lista di immagini panoramiche per i controlli integrati. Dettagli nei prossimi capitoli.
bgcolor	Colore dello sfondo, da fornire in valore esadecimale.
hsimage	Nome dell'immagine che fornisce la sagoma per tutti gli hotspot. questa immagine deve avere le dimensioni identiche all'immagine panoramica. Si veda il capitolo hotspot per maggiori informazioni.
sound 0, sound 1, sound 2, ...	Nomi dei suoni da usarsi nell'applet.
quality	determina quale dei due intrepolatori di pixel integrati vengono usati per rappresentare le immagini. sia il metodo "nearest-neighbor" o l'interpolatore bilineare. Le opzioni disponibili sono 0 = sempre nn; 1 = nn durante la rotazione, bilineare per le immagini ferme; 2 = nn durante la rotazione manuale, bilineare per le immagini ferme e per l'autorotazione; 3 = sempre rotazione bilineare. (predefinito; 3)
inits	Comando di inizializzazione che viene eseguito dopo che il panorama viene caricato. Questo può essere un comando PTViewer o Javascript oppure un URL. Deve essere usata la stessa sintassi come nel tag 'u' degli hotspot. "inits" può anche collegare a un target all'interno dell'URL. In questo caso "inits" deve contenere l'URL e il target separati da un '*' (Es. <PARAM name=inits value="http://www.mysite.com*_blank">
applet0, applet 1, applet 2, ...	Applets da caricare all'interno di PTViewer. Usare questa funzione per caricare filmati panorama, Objects o le altre applet aggiuntive.
preload	Lista i immagini separate dalla virgola che verranno caricate a priorità bassa. Utile per tour VR con molte immagini panoramiche. Saranno disponibili istantaneamente senza ritardi.
cache	Da impostare a "false" se si vuole disabilitare la chache interna per le immagini di PTViewer. Utile per immagini molto grandi che non sarebbero contenute nella RAM.
cursor	Impostare a CSOSSHAIR o MOVE per cambiare la freccia del cursore. Il cambiamento avviene solo quando il cursore è sopra all'applet.
loadAllRoi	Impostare "false" per disabilitare il caricamento di tutte le sezioni ROI al momento dell'avvio dell'applet (Predefinito: "true")
grid_bgcolor	Valore esadecimale che specifica il colore della griglia di sottofondo (predefinito: bianco) La griglia viene mostrata se è attivo lo scaricamento delle sezioni ROI. Si vede il capitolo sulle ROI per maggiori informazioni
grid_fgcolor	Valore esadecimale che specifica il colore della griglia di sfondo (predefinito: nero).La griglia viene mostrata se è attivo lo scaricamento delle sezioni ROI. Si vede il capitolo sulle ROI per maggiori informazioni
mass	Si puo aggiungere un eggetto inerzia all'applet usando una massa virtuale. Questo parametro influenza la risposta del visualizzatore ai cambi di direzione.. Questo parametro viene preimpostato a 0 per non avere alcun ritardo nella risposta al movimento. Si possono assegnare valori da -10 a +30.
antialias	Impostata "true" questa opzione attiva la funzione "antialias". E' supportato dalle immagini pnoramiche equirettangolari. dalle immagini QTVR (cilindriche e cubiche) e dalle immagini PTZoom. per dettagli vedere questo esempio example
oversampling	Questo paramero viene usato con la precedente opzione antialias. determina il massimo rapporto tra risolizione originale (pixel/gradi) e risoluzione di schermo (pixel/gradi). il valore predefinito è 1.5. Valori più grandi mostran immagini più nette, con valori più piccoli l'immagine viene ammorbidita.
order	Parametro usato con i virtual QTVR. determina l'ordine delle sezioni (nel caso dei panorami cilindrici) o delle immagini delle facce del cubo (nel caso dei panorami cubici). Se questo ordine non è standard come nel caso che il virtual QTVR sia stato appiattito, questo paramentro deve contenere una lista di numeri separati da virgole che indica la posizione delle immagini (Es. <PARAM name=order value=4,3,1,5,7,2,0,6>)

5d) Liste di panorami

<PARAM name=hotspot0 value="x1141 y207 u'pano.html' n$+Marciana 'Marina'+ ">
Ogni Hotspot viene descritto con 4 parametri obbligatori:

xnumber  o Xnumber - La coordinata x dell'hotspot. 0 è il punto più a sinistra espressa in valore assoluto di pixel (0 / larghezza massima), oppure espressa in valore relativo percentiale (0...100), sono ammessi valori frazionali.
ynumber  o Ynumber - La coordinata y dell'hotspot. 0 è il punto più in alto, espressa in valore assoluto di pixel (0 / altezza massima), oppure espressa in valore relativo percentiale (0...100), sono ammessi valori frazionali.
n'name' - Nome dell Hotspot mostrato nella barra di stato quando il mouse viene posto sopra di esso. Va racchiuso tra virgolette singole (').
u'name' - il nome dell indirizzo (URL) al quale si vul collegare l'hotspot. Va racchiuso tra virgolette singole ('). Al posto di un URL, si puo specificare un quasiasi comando di ptviewer utilizzando il prefisso "ptviewer:".

chexnumber - Il valore espresso in forma esadecimale RRGGBB - del colore del marcatore hotspot. Il valore di default è il rosso.

i'name' - nome dell'immagine da mostrare quando l'hotspot viene attivato. Può essere una GIF o JPG e sarà mostrata centrata rispetto alle coordinate specificate nell'hotspot. Al posto dell'immagine è possibile specificare uno dei comandi di Ptviewer. Il comando verrà eseguito quando il mouse entra nell'hotspot.
Esempio:

<PARAM name=hotspot6 value="  x776  y124  n'Lamp' i'ptviewer:PlaySound(0)' u'Controls.html'  ">

Questo hotspot riproduce un sound numerato 0 quando il mouse entra sulla zona sensibile. I comandi eseguiti dagli hotspot sono sempre del tipo "popup" e non reagisscono con il comando showHS(). Se viene usato il parametro 'e', allora 'i' specifica una finestra di testo; si veda più avanti.

t'name' - nome dell'ancora nel documento html specificato con l'opzione u.
m'name' - nome di una immagine da usare come maschera per la forma dell'hotspot. Gli hotspot normali sono dei quadrati di 20x20 pixels. Per impostare altre forme utilizzare una immagine GIF bianca nelle parti che devono essere sensibili. Questa immagine si posizionerà nel punto a sinistra in alto specificato dalle coordinate x e y dell'hotspot . L'a sagoma dell'hotspot apparirà centrato rispetto alle coordinate.
p - Specificando p (senza parametri) l'immagine dell'hotspot viene evidenziata quando il mouse vi si trova sopra.
q - specificando q (senza parametri) l'hotspot è sempre visibile. opzione usabile per la creazione di logo volanti.

w - Specificando w ( 'warped', senza parametri) fa si che l'immagine specificata nel tag "i" venga inserita nell'immagine panoramica invece che nella finestra dell'applett. In questo modo l'immagine è ancorata allo sfondo. Questa possibilità sia che per gli hotspot permanenti sia per quelli normali. L'immagine viene inserita centrata alle coordinate x e y. Si noti che x,y = 0,0 è l'angolo in altoi a destra. L'immagine deve essere più piccola o riempire l'immagine panoramica e deve esere di forna rettangolare, l'area dell'immagine è la regione attiva, a meno che non venga specificata separatamente una maschera.

e - Specificando e (senza parametri) fa si che il parametro "i" venga interpretato come testo. Il messaggio viene mostrato in una finestra rettangolare autodimensionata con l'angolo in alto a sinistra, segnalato da un punto, determinato dalle coordinate x e y. Per nadare a capo si usa il carattere '|'. Con il parametro "c"(vedi più avanti)si specifica il colore del testo.
Esempio:
<PARAM name=hotspot0 value=" x10 y20 n'nome' i'Questo è| un messaggio' e">

a number or A number - la coordinata x del vertice sinistro di un hotspot rettangolare con a minuscolo va espressa in pixel assoluti (0...larghezza), specificando la A maiuscola si avra una coordinata relativa (0...100). Se a o A vengono specificate la zona attiva dell'hotspot è un rettangolo con coordinate sinistra x e destra a. Il marcatore dell'immagine verrà mostrato centrato. Si noti che un rettangolo nell'immagine panoramica viene distorto nella finestra del visore. Se si vuole ottenere la forma esatta allora si deve usare il tag m per un hotspot mascherato.
b number or B number -la coordinata y del vertice destro di un hotspot rettangolare con b minuscolo va espressa in pixel assoluti (0...altezza), sepcificando la B maiuscola si avrà una coordinata relativa (0...100). Sono ammessi valori frazionari. Se b o B vengono specificate la zona attiva dell'hotspot è un rettangolo con coordinata sinistra x e coordinata destra a Uno tra b e y deve essere l'alto, l'altra coordinata è il basso del rettangolo. Il marcatore dell'hotspot viene mostrato centrato. Si noti che un rettangolo nell'immagine panoramica viene distorto nella finestra del visore. Se si vuole ottenere la forma esatta allora si deve usare il tag m per un hotspot mascherato.

Ecco alcuni esempi di parametri per gli hotspot:

 

Hotspot statici

xnumber  -coordinata x sinistra
ynumber   - coordinata y superiore o inferiore
anumber  - coordinata x - destra
bnumber   - coordinata y superiore o inferiore
u'name' - URL del documento collegato relativo alla pagina html, incluso con single quote ('). In alternativa si può inserire un comando ptviewer usando il prefisso "ptviewer:".

t'name' - Nome del link specificato nel documento con l'opzione 'u'.
i'name' - nome dell'immagine da mostrare quando l'hotspot viene attivato. può essere una gif o una jpeg, e verrà mostrata allineata in alto a sinistra, in coincidenza con le coordinate x e y specificate. L'immagine non verrà mostrata se non si specifica uno dei due paramerti p o q oppure se non viene eseguito il comando DrawSHSImage(). Al posto di un'immagine si puo specificare uno quasiasi dei parametri di ptviewer. Questo comando sarà eseguito quando il moise entra nella regione dell'hotspot.
p- (senza parametri) rende l'hotspot visibile solo quando il mouse si muove sopra di esso.
q-(senza parametri) rende l'hotspot sempre visibile.

  

i'name' - nome dell'immagine da inserire (richiesto).
x'number' - coordinata orizzontale in pixel del punto di insersione (angolo in alto a destra dell'immagine). Default: 0
y'number' - coordinata verticale in pixel del punto di insersione (angolo in alto a destra dell'immagine). Default: 0.

Per default, tutte le immagini ROI vengono caricate e inserite al momento dell'inizializzazione. La funzione può essere disabilitata impostando il loadAllRoi = "false". In tal caso è possibile caricare immagini ROI individuali usando il comando ptviewer:loadROI( int number) (o la corrispondente versione Javascript). Questo comando può essere collegato a qualsiasi hotspot o controllato da un javascript (si veda la sezione riguardante lo scripting).
Se non viene impostato nessun parametro "virtual" nonostante venga impostata la larghezza del panorama con "pwidth", allora Ptviewer mostrerà una griglia con linee orizzontali e verticali spaziate di 10°. La griglia verrà riempita progressivamente dalle immagini ROI mostrando un caricamento progressivo. I colori di sfondo e quello delle linee della griglia possono essere impostati con i parametri "grid_bgcolor" and "grid_fgcolor" che, per default, sono impostati rispettivamente a nero e bianco.
Fattori di zoom maggiori di 3:1 vengono trattati in modo ottimale utilizzando l'estensione PTZoom.

Sono supportati file audio di tipo au, aiff, wav e midi. Per utilizzarli vanno specificati in una lista usando i parametri sound0, sound1, sound2, ecc. Per riprodurre i suoni va utilizzato il comando 'PlaySound(n)' ove n indica il numero del suono specificato nella lista. Questo comando può essere collegato a un qualsiasi hotspot statico, oppure a una funzione "popup", o anche essere chiamato da una funzione con javascript.
Si noti che alcuni browser di vecchio tipo con vecchie java virtual machine potrebbero avere difficoltà a riprodurre suoni diversi dal formato .au.
Per riprodurre suoni in formato '.gsm' esite un'apposita estensione.
Molti altri formati sono disponibili se sul pc che esegue ptviewer è istallato JMF. Con jmf installato sono utilizzabili filmati AVI, quicktime, Flash, mpeg 1/2/3, e molti formati audio.
Dalla versione 1.72 di Ptviewer i contenuti jmf vengono caricati con l'estensione opzionale PTMedia.

Dalla versione 1.1 PTViewer puo essere configurato internamente per controllare quasi tutte le funzioni. Non è richiesto un browser per mostrare un Tour Virtuale che può essere mostato completamente con l'applett.

The basis for this is an internal scripting system which works like a subset of javascript. Many PTViewer-functions can be called like URLs using the prefix "ptviewer:". They can be used as u-tag in both static and normal hotspots, see the examples for static hotspots above. This is a list of accessible functions which is similar to the corresponding list of javascript functions:
 

Some functions require arguments, eg. startAutoPan(). These arguments should be supplied as constants. Allowed is  startAutoPan(2,3,1.2), not allowed is startAutoPan(1+0.5, tilt, zoom*1.05).

PTViewer can be scripted by the html document. Several functions are available to control navigation, zooming, panning and jumping to specific locations. The syntax follows the usual javascript rules. All ptviewer commands from the list above are available as javascript commands also. In addition, the following commands are available only in javascript:

See the html virtual ditributed with the java viewer for an example. It uses an image map created by Andrei Bodrov  and links some of the controls to specific buttons. You may also link to standard javascript buttons in your document as used for the 'gotoHS' links.

For a more descriptive list of all publicly accessible parameters and functions in ptviewer, see the API-documentation generated using javadoc.

Loading New Panoramas from Running Applets

New Panoramas can be loaded using the newPano() and newPanoFromList() functions. The newPanoFromList() function requires the previous definition of a list of panoramas, whereas the newPano() function supplies all definitions in a string argument.

Both functions  can be used from internal controls using the URL-tag 'ptviewer:newPanoFromList(num)', in hotspots (normal and static hotspots) or using javascript from the browser. All parameters are reset with the exception of the view-parameters (width/height/offset), the wait image, the frame image, all static hotspots and  sounds.Static hotspots, frame, wait image and  sounds may be newly set in the panorama description, in which case the old values are discarded. See the example Controls.html of the distribution.
 
 

Calling Javascript functions from PTViewer

PTViewer can call user supplied javascript functions. To be able to call javascript from the applet, the parameter mayscript must be set. This can be done in the applet tag:
 

<APPLET  name="ptviewer" archive=ptviewer.jar  code=ptviewer.class width=320 height=200 mayscript=true>

There are three possible ways to call javascript from PTViewer:

 My own tests have shown that interaction of javascript with java may be quite unstable and does not work on all browsers, eg not on the combinations Mac/IE. It is recommended to check for a safe combination by query of the javascript navigator object, and provide an alternative for unsafe systems.
    

Some browsers have limits on the maximum size of linear arrays, eg 4MByte on Netscape, even if more system memory is available. This limits the maximum size of images some java viewers can handle, eg LivePicture's IVR-viewer can't read spherical images of more than 1500 pixels width. PTViewer can read much larger images by internally splitting the image into chunks of smaller pieces. The size of these chunks can be set via 'maxarray' parameter tag. The default value is #80000 hexadecimal, which corresponds to roughly 500000pixels, ie 2Mbyte (4byte = 1pixel). Unfortunately, this splitting causes other Browsers (Internet Explorer) to download images slower than normal. For best performance one can set the maxarray parameter depending on the browser, see the javascript code in the example above. However, in most cases this is not needed and the default value works for any browser.
 

Packaging virtuals using the Jar utility

All virtuals belonging to a VR-scene (images, sounds, textvirtuals) can be packaged into one single archive using the Jar archiving tools. This is a convenient way to store, mail and present  virtual tours. Only the html-virtual has to be kept separate. Double-clicking this html-virtual launches the browser, which then automatically extracts and displays the content of the virtual. See the separate documentation about packaging tours for details.
 

From version 0.8, PTViewer has some additional helper commands to aid authoring of documents:

PTViewer Java Application

This application uses the Java-applet 'PTViewer' and a custom AppletStub to implement a standalone cross platform spherical panorama viewer. Using the internal scripting capability of PTViewer, full featured VR-tours can be displayed. The same html-virtual used for display in a browser can be reused for the application.Using the Java archiving tool 'Jar', it is possible to pack tours into one self-displaying virtual. See the separate documentation describing this feature.
 

After double-clicking the application, a virtual dialog is presented. Choose any panoramic image in jpeg format, eg the virtual pano.jpg in the distribution. Images are recognized by the extension jpg or jpeg. Alternatively, you may specify a html-virtual, eg the virtual example.html. PTViewer extracts the <applet>-tag and all parameters relevant for display, and shows exactly the same tour as can be seen in a browser, with the following restrictions:

The application allows the user to resize the viewer window. If the viewer-size has not been set (parameter view_width and view_height), the applet will also be resized according to the window. If the viewer-size has been set (most likely to fit the applet into a frame) then the applet does not react to window size changes. Do not resize the window while the applet loads the image.

PTViewer does not display a virtual dialog if a html-virtual with name 'default.html' is present in the applications directory. PTViewer then loads and processes this virtual. This can be used for self-displaying tours. PTViewer may also be called by other java applications. The main() method of the ptvjapp class should be called with the virtualname of an image or html-virtual  as argument.
 

Commands and applet tags which are used frequently may be put into a separate virtual named 'PTDefault.html'. The syntax for providing commands is identical to the newPano() function. Example:

{wait=wait.jpg}{bar_x =187}{bar_y=283}{bar_width=302}{bar_height=25}

The defaults virtual may also be packaged into the PTViewer.jar virtual together with any auxiliary images like hotspot buttons, frames or wait images thus providing a convenient way to customize the viewer.
 
 

Extensions: PTObject, PTMovies, PTCompass, PTMedia, PTZoom

Using the API-documentation, it is possible to extend PTViewers capabilities using additional applets. Five such applets are included in the distribution: PTObject, PTMovies, PTCompass, PTMedia and PTZoom. See this documentation about the use of these applets, and how to build your own extensions.

More Resources and Examples:

License

PTViewer is distributed under GNU license, see the virtual 'Copying' in the distribution.