Questo tutorial ha volutamente la forma essenziale di un HowTo ("come fare a..."); si tratta quindi di una serie di informazioni procedurali, corredate da una minimale trattazione teorica, che riguarda quanto è necessario per pubblicare sul web una fotografia navigabile usando il player Krpano. Krpano è in evoluzione come gran parte dei player e l'autore continua a produrre aggiornamenti, attualmente (marzo 2010) siamo alla versione 1.0.8 beta 9, a cui faremo riferimento in questo scritto.

Nell’articolo non si parla delle modalità di scatto nè delle tecniche di stitching che consentono di ottenere un'immagine panoramica. Queste questioni sono già state autorevolmente affrontate da altri autori su questo stesso spazio web; qui si tratta esclusivamente del passaggio successivo: come pubblicare sul web una fotografia panoramica navigabile (equirettangolare, cubica o un panorama parziale, a media o altissima risoluzione).

Prima di tutto è doveroso ricordare che Krpano è ideato, prodotto e gestito interamente da un solo autore. Si tratta di un programmatore austriaco di nome Klaus Reinfeld, che "oltre al suo lavoro" ha prodotto tutta da solo questo software. Qualche tempo fa (peccato non sia indicato quanto) ha rilasciato questa intervista per la rivista digitale vrmag. Lo stesso Klaus modera un forum sul suo spazio web e interviene spesso, anche per rispondere a semplici domande dirette dei suoi utenti.

1. L'ARCHITETTURA DI KRPANO

Il player Krpano è strutturato sull'azione combinata di una serie di files (almeno 3). Questi files cooperano fra loro per interpretare un' immagine (o una serie di immagini), deformarle, proiettarle sull'output, generando le animazioni, gli effetti dinamici, le transizioni ecc.

I files sono scaricabili (con funzionalità complete anche nella versione di prova) dal sito di krpano a questo indirizzo. Il download consiste di una cartella che comprende numerosi esempi riguardanti le varie opzioni offerte dal player, gli esempi sono corredati da immagini a bassa risoluzione (si tratta di proiezioni equirettangolari e/o cubiche singole o multitiles).

Assieme al player è possibile scaricare (ed eventualmente acquistare con una licenza a parte) Krpanotool: una serie di utili strumenti per l'elaborazione dell'immagine. I tools di Krpano consentono per esempio di passare da cubica a una equirettangoalre e viceversa, ma l'interesse maggiore va rivolto a kmaketiles: lo strumento che ha reso Krpano il player più performante per immagini ad alta risoluzione. kmaketiles è un tool per il tiling. Il tiling è l'operazione di ritaglio delle immagini ad alta risoluzione che vengono suddivise in tante piccole parti (in inglese tiles) per rendere l'immagine disponibile su più livelli e scarcabile attraverso il web con tempi di attesa ragionevoli.

Nella trattazione che segue faremo esplicito riferimento ai files e agli esempi scaricabili dallo spazio web di krpano, indicando fra parentesi i nomi dei files e/o i percorsi relativi all'interno della cartella da scaricare (la cartella di download). Ovviamente i nomi di tutti i files possono essere modificati a piacere dall'utente, a patto di conoscere e cambiare anche i riferimenti relativi che li associano fra loro. Capiterà certamente che (magari in occasione di un aggiornamento del software) i nomi dei files di esempio siano modificati dallo stesso Klaus. Non importa, la struttura generale che di seguito è illustrata è destinata a rimanere valida. Probabilmente prima o poi uscirà anche una GUI per Krpano (magari del tipo WYSIWYG), tuttavia credo che sarà comunque utile conoscere l'architettura del player. L'architettura più semplice di Krpano è composta dei seguenti 4 elementi (diciamo 4 files):

A) un file (o una cartella di files) immagine. E' l'immagine da proiettare (per esempio nella cartella scaricabile dal sito di krpano se ne trova una in examples\buttons\pano.jpg). Tipicamente il formato finale dello stitching viene trasformato in .jpg prima di "passarlo" a krpano. Le recenti versioni di Krpanotool consentono di partire anche dal formato .tiff, o .psb (utile per i gigapanorami) o anche .mov. e usare o ottenere direttamente il formato .swf. Comunque nella maggioranza dei casi i panofotografi usano come formato finale dello stiching da dare a Krpano un file .ipg..
Le dimensioni in pixel del file possono essere quelle di una proiezione equirettangolare (lato corto*2= lato lungo), oppure cubica (6 files separati o le sei facce in un solo file). Le versioni più recenti di Krpano riconoscono e interpretano anche panorami parziali (come proiezioni cilindriche con angoli verticali inferiori a 180° o anche panorami con valori di angoli orizzontali minori di 360°). Sui formati immagine da "dare in pasto" al player torneremo più avanti.

B) un ("il") file player in formato .swf (krpano.swf nella cartella dowload): si tratta del player vero e proprio. L'estensione .swf è il formato proprio dei files di flash il noto prodotto di Macromedia ora incorporata da Adobe. Per la lettura di questo file da pare del Browser si rende necessaria l'installazione del plug-in macromedia flash player. che è molto diffuso e comunque facile e veloce sia da scaricare che installare. Il file krpano.swf ha il compito di interpretare (se è necessario anche ricomporre) l'immagine, deformarla, e proiettarla sull'output. La licenza del player di fatto è relativa all'uso del file krpano.swf: gli altri 2 files almeno per la configurazione di minimo sono infatti dei files di solo testo:

C) un file .xml (per esempio krpano.xml). Il file krpano.xml che si trova nella cartella di download non apre una panoramica ma una serie di azioni e comandi di esempio, che lo rendono complicato da comprendere. Per cominciare è più facile considerare qualcosa come il files exsamples/buttons/buttons.xml. Il file nel formato .xlm è un testo può essere letto ed editato con il semplice notepad di windows; serve per "passare" alcuni parametri al player (il file krpano.swf). Di fatto il file .xml consente al file .swf di trovare l'immagine da proiettare, e poi di interpretarla correttamente. Nel file .xml si impostano in modo opportuno una serie di parametri disponibili; per fare un esempio l'angolo di vista (filed of view) viene indicato così nella sintassi propria dei files.xls

....
fov="90"
fovmin="60"
fovmax="120"
...

Le regole per scrivere un file .xml sono piuttosto rigide e non è disponibile un debag avanzato; ma sul sito krpano.com alla sezione documenti sono presentate tutte le righe di comando ognuna ampiamente commentata. Vengono inoltre forniti dei semplici esempi di codice.
Infine, ad onor del vero, va detto anche che quando si "visita" una panoramica sul web il relativo file .xml viene anch'esso scaricato dal lato client. Perciò il file .xml della panoramica è rintracciabile nel cache del browser, cosa che ovviamente mette a "disposizione" moltissimi esempi operativi a cui diciamo "ispirarsi" (un testo è pur sempre un testo).
Un file .xml può "richiamare" a sua volta altri files .xml o .swf (anche su questo torneremo più avanti).

D) il quarto elemento è un file .html o htm (per esempio krpano.html), Il file .html costituisce la pagina web nella quale si vede la fotografia navigabile. Nella dinamica client-server della rete il file .html è il file che viene richiesto e processato per primo dal browser; anche questo file è un solo testo. L'html contiene fra i sui tag i riferimenti ai files .swf e al file .xml. che consentono di includere la panoramica della pagina web.
Anche se non è strettamente necessario è comunque molto opportuno (e raccomandato dallo stesso Klaus) includere i riferimenti ai precedenti files mediante un breve script. Solo in questo modo è possibile generare un messaggio di errore per un eventuale utente che non ha intallato flash player e invitarlo ad eseguire il download; oppure re-indirizzarlo ad un altra pagina web ecc.
Un' inconveniente di questa procedura è il fatto che per far “vedere” al browser il player, si deve inserire nell’html qualche riga di javascript, con l’ovvia conseguenza che l'utente finale deve avere installato anche java (comunque gratuito e molto diffuso) anche in questo caso è possibile avvisare e reindirizzare al download. Per far questo krpano si serve di un altro piccolo file: swfkrpano.jf (che, per il momento, è l'ultimo da considerare).

Uno schema grafico dei diversi files (diventati 5) finora citati e dei loro reciproci rapporti:

2. COME IMPOSTARE I RIFERIMENTI per collegare i files fra loro

Nel file .html di esempio i riferimenti che "richiamano" gli altri 3 file sono i seguenti:

a) il riferimento al file swfkrpano.js:

< script type="text/javascript" src="swfkrpano.js"></script>

b) il riferimento al file krpano.swf ( in grassetto nel bocco di codice "cod1")

<script type="text/javascript">
// <![CDATA[
var swf = createswf("krpano.swf", "krpanoSWFObject", "100%", "100%");
swf.addVariable("xml", "krpano.xml");
swf.embed("krpanoDIV");
// ]]>
< /script>

La quinta riga dello script suggerisce che nel corpo [body] della pagina html si include l'oggetto krpano.swf usando il tag div, così per esempio:

< div id="krpano"></div>

tutti i riferimenti sono relativi alla posizione del file .html e possono essere cambiati usando percorsi relativi: così se, per esempio per ragioni di ordine, preferisco posizionare il file il file krpano.swf nella cartella "swfobject" la riga 3 dello script precedente deve essere modificata in:

var swf = createswf("swfobject/krpano.swf", "krpanoSWFObject", "100%", "100%");

lo stesso vale per ogni altro cambiamento di percorso

c) il riferimento al file.xml è realizzato dalla quarta riga del blocco di codice precedente (cod1). il file .xml contiene a sua volta i riferimenti che richiamano le immagini. Le righe di codice xml che "collegano" le immagini sono diverse a seconda del tipo di immagine scelto, nel caso più semplice (il riferimento ad una panoramica costituita dalla una sola immagine cubica presa ad esempio ) le stringhe sono le seguenti: ("cod2")

<image type="CUBESTRIP">
< cubestrip url="pano.jpg" />
< /image>

dove [image type] definisce il tipo di immagine (una proiezione cubica di un solo file) e [cubestrip url] indica il percorso relativo al file (nell’esempioil file è “pano.jpg”). Anche in questo caso può essere modificato il percorso: così se per esempio preferisco posizionare l'immagine "pano.jpg" nella cartella "miapano" il riferimento nella seconda riga del cod2 deve essere modificato così:

<cubestrip url="miapano/pano.jpg" />

il codice .xml può essere commentato secondo la sintassi <!-- commento --> d'ora in poi useremo questa modalità per i commenti.

3. INCLUDERE altri files .xml

i files .xml possono essere collegati fra loro come se fossero "nidificati". Cioè un file .xml può contenere riferimenti ad altri files.xml. Questa tecnica consente di risparmiare spazio si evita di usare codice ridondante, e tempo nel download. Questa riga di un file .xml ne richiama un altro:

<include url="buttons-png-include.xml" /> <!-- include i comandi di movimento-->


4. INCLUDERE altri files .swf

attraverso lo stesso sistema possono esser "coinvolti" anche altri file .swf che funzionano come un sorta di "parte esterna" del file Krpano.swf. Vengono anche chiamati "plug-in", un esempio:

....
< plugin name="maps"
url="swfobject/googlemaps.swf" <!-- include il plug-in googlemaps.swf per googlemaps (a pagamento) -->
....
>
.....

Con i plug-in si accede a molte funzioni multimediali come campi testo, combobox, videoplayer, sound ecc. a questo indirizzo l’elenco dei plug-in disponibili. Nella cartella di esempio scaricabile c’è anche la sottocartella “plugins” con i relativi file.swf. Un’attenzione particolare meritano i plug-in “editor” e “options” su cui torneremo dopo.


5 MODIFICARE GLI ATTRIBUTI DELLE PANORAMICHE

Per modificare il modo in cui il player mostra l'immagine panoramica occorre impostare i valori dei singoli attributi nel file .xml che è associato all'immagine. In molto molto generale si consideri che:
- l'ordine interno dei singoli attributi non è significativo;
- si deve porre grande attenzione ai simboli < e /> che "aprono e chiudono" blocchi di attributi
- si deve porre grande attenzione alle virgolette " " che indicano i valori o i parametri e
- ai punti e virgola ";" che funzionano come delle "congiunzioni".

esemplificando:

< view hlookat ="-80" <!-- indica il punto sul piano orizzontale da dove iniziare a mostrare l'immagine -->
vlookat ="-15" <!-- indica il punto sul piano verticale da dove iniziare a mostrare l'immagine -->
fov ="45" <!-- indica in gradi l'ampiezza dell'angolo di vista iniziale -->
fovmin ="24" <!-- indica in gradi l'ampiezza minima dell'angolo di vista -->
fovmax ="70" <!-- indica in gradi l'ampiezza massima dell'angolo di vista -->
limitfov ="true" <!-- indica se (in questo caso) lomitare la variazione dell'ampiezza dell'angolo di vista -->
...
/>

alcuni blocchi di attributi sono contestuali fra loro e si riferiscono allo stesso attributo, perciò sono delimitati dalla sintassi <blocco di attributi /> , per esempio

< autorotate enabled ="true" <!-- indica che l'autorotazione è attiva -->
waittime="10" <!-- indica quanto attendere dall'ultima zione prima di far partire l'autorotazione -->
accel ="1.0" <!-- indica l'accelerzione dell''autorotazione -->
speed ="5" <!-- la velocità massima -->
horizon ="off" <!-- se portare sul piano orrizontale automaticamente -->
...
/>

Tutti gli attributi disponibili con loro sintassi e i possibili valori dei parametri sono elencati e commentati (in inglese) sulla sezione documentazione del sito krpano.com.

6 LE AZIONI

Nei file .xml possono essere incuse anche delle azioni, attivabili in risposta a determinati eventi. per esempio:

<plugin name="fs" <!-- definisce il nome dell’azione -->
url="swfobject/btn_openfs.jpg" <!-- assegna un’ immagine all'operatore -->
....
onover="set(plugin[fs].blendmode,add);" <! -- al passaggio del mouse setta il plug-in modalità blendmode -->
onhover="showtext(fullscreen on/off);" <! -- all'evento _ puntatore sopra _mostra il testo “fullscreen on/off” -->
onclick="switch(fullscreen);switch(plugin[fs].url,swfobject/btn_openfs.jpg,swfobject/btn_closefs.jpg);setfov(65);"
<!-- al click passa alla modalità fullscreen cambia l’immagine associta al plug-in e setta il fov a 65° -->
....
/>

al solito su krpano.com c’è l’elenco commentato delle azioni disponibili (che sono moltissime).

NB: L'architettura precedentemente descritta non deve essere sempre ricostruita attraverso l'editing del testo o mediante dei laboriosi "taglia e incolla". Infatti krpanotool mette a disposizione uno strumento per scrivere in automatico i file .html e .xml per ogni nuova immagine panoramica che viene processata. Inoltre krpanoplayer contiene un vero e proprio editor per i file .xml. Torneremo su queste funzionalità dopo aver analizzato, nel punto che segue, lo strumento di tiling.


7 TILING CON KRPANOTOOLS

<krpano version="1.0.8>
<!--dichiara la versione di Krpano-->

< include url="skin/defaultskin.xml" />
<!--include il contenuto del file “defaultskin.xml” nella cartella “skins” che gestisce gli eventi e i comandi di moto-->

<view hlookat="0" vlookat="0/>
<!-- definisce il punto di partenza della sferica-->

<display details="22" />
<!-- indica il numero delle linee generate da flash-->

< preview type="CUBESTRIP" url="mia_pano.tiles/preview.jpg" />
<! -- indica i riferimenti all’immagine di anteprima -->

<! -- di seguito i riferimenti alle tiles che compongono l’immagine sferica -->

<image type="SPHERE" multires="true" tilesize="625">
<level tiledimagewidth="10000" tiledimageheight="5000">
<sphere url="mia_pano.tiles/l4_%0v_%0h.jpg" />
</level>
<level tiledimagewidth="5000" tiledimageheight="2500">
<sphere url="mia_pano.tiles/l3_%0v_%0h.jpg" />
</level>
<level tiledimagewidth="2500" tiledimageheight="1250">
<sphere url="mia_pano.tiles/l2_%0v_%0h.jpg" />
</level>
<level tiledimagewidth="1250" tiledimageheight="625">
<sphere url="mia_pano.tiles/l1_%0v_%0h.jpg" />
</level>
</image>

</krpano>

Anche i files templates sono semplici da personalizzare a titolo di esempio prendiamo “default.xml”, da confronto del codice che segue (cod4) con il cod3 si capisce come viene interpretato dal tool il file modello.

<!-- questa prima parte viene copiata -->

<krpano version=”1.0.8”[PARTIALPANO]>
<include url=”skin/defaultskin.xml” />
<view hlookat=”0” vlookat=”0” maxpixelzoom=”1.0” />
< display details=”22” />

<!-- di seguito al posto delle parole fra parentesi quadre kmakemultires.exe inserisce i riferimenti alle immagini-->

[PREVIEW]

[IMAGE]

Ad altre impostazioni automatiche del file kmakemultires.exe si possono avere trascinando i files immagine sopra i files con estensione .bat presenti nella cartella dei tools, il nome del file ne anticipa le funzioni. La dinamica è la stessa vista in precedenza, con la sola differenza che si usano impostazioni previste da altri file .xml della cartella templates. Anche questi files possono essere editati:ecco per esempio il contenuto del file MAKE PANO (NORMAL) droplet.bat

@echo off
echo MAKE PANO (NORMAL) droplet
IF "%~1" == "" GOTO ERROR
IF NOT EXIST "%~1" GOTO ERROR
"%~dp0\kmakemultires" "%~dp0\templates\normal.config" %*
GOTO DONE
:ERROR
echo.
echo drop panoramic images to create automatically
echo normal (not-tiled, not-multiresolution) panoramas from it...
:DONE
echo.
pause

Non tratteremo di queste modifiche.


9. STRUMENTI DI SVILUPPO IN KRPANO: editor.swf e options.swf

Krpano mette a disposizione una sorta di “ambiente di sviluppo” che permette di scrivere in automatico alcune parti del codice .xml e contemporaneamente vederne gli effetti che le modifiche producono. Il sistema sfrutta i 2 plug-in “editor.swf” e “options.swf”. Per usarli in occorre prima creare una panoramica navigabile con tutti i files annessi e poi copiare nel file .xml queste due righe (attenzione ai riferimenti relativi per l’attributo “url= ....” )

<plugin name="editor" url="editor.swf" />
< plugin name="options" url="options.swf" />

Poi si lancia il file .html (come si farebbe normalmente per vedere la panoramica), a questo punto gli strumenti sono accessibili direttamene dalla finestra del browser. La modalità di utilizzo è relativamente intuitiva:
- il plug-in options è un menù a cascata in alto a destra.
- alle funzioni del plug-in editor si accede con un comando in basso.

Fatte le opportune scelte è possibile salvare il nuovo file .xml, o ripartire da quello originle, copiarne parti ecc. Due esempi:

Il menu options aperto

I

l’aspetto dell’editor:

10. TRASFERIMENTO FTP

Dopo aver testato tutto in locale, non resta che effettuare il trasferimento su un server mantenendo la stessa struttura delle cartelle e la posizione relativa dei files, lo spazio sul server non necessita di altre opzioni. Per usare krpano on-line occorre ovviamente avere la regolare licenza, che viene fornita ... con un ultimo file, che deve essere incluso con un'ultima riga di html . ;-))