krpano XML 레퍼런스

krpano 도구는 여러가지 도구들의 집합입니다. 다양한 요소로 이루어져 있어 잘만 조합하면 원하는 것을 마음대로 바꿀 수 있지만, 그만큼 매우 까다롭습니다. 

예전에 정리한 kmakemultires 도구는 주로 360*180 파노라마 영상을 처리하는 도구입니다. 즉, 이미지의 포맷을 바꾼다던지 (spherical <-> cubical 등) 이미지 피라미드로 구성한다던지, thumnail 이미지를 만든다던지, 영상의 크기를 바꾸고 압축을 하는 등 이미지를 처리하는 거의 모든 기능이 들어있다고 할 수 있습니다. 

이번에 정리한 krpano XML 파일은 주로 뷰어의 형태를 다룹니다. 즉 kmakemutires 도구에서 처리된 영상을 읽어들여서 기본적인 형태로 보여준 뒤, layer(plugin)/hotspot 등을 사용하여 버튼/아이콘 등을 배치하여 기능적으로 쉽게 사용할 수 있도록 해주는 것입니다. 실제로 버튼을 누르거나 마우스를 움직이던가 등등의 이벤트가 발생할 때 어떻게 동작할 것인가는 <action> 혹은 function()에 지정하는데, 다음번에 정리할 예정입니다.

참고로, 이글은 제가 생각나는대로 정리하기 위한 목적이기 때문에 읽는 분들에게는 크게 도움이 안될 겁니다. 부디 그냥 그러려니 하고 pass 하시길.

====

krpano 도구는 간단한 XML 파일을 사용하여 파노라마 설정을 저장. 이 파일은 일반 텍스트 에디터로 생성/편집할 수 있지만, XML 규칙을 반드시 따라야 함.

기본 XML 규칙 : http://www.w3schools.com/xml/xml_syntax.asp

이 문서에 관하여

krpano XML 문법 및 요소, 속성 및 속성값. 그리고 이들을 동적 krpano 변수에 매칭시키는 방법. 일반/고급 부분. 읽기 좋게 하려는 목적. 고급 부분은 감춰둠. 오른쪽위 버튼을 누르면 볼수 있음. 

XML 태그의 구조

<krpano> - root 노드. 

    <include>

    <preview>

    <image>

    <view>

    <autorotate>

    <plugin>

    <layer>

    <hotspot>

    <events>

    <action>

    <scene>

</krpano>

<krpano> - root 노드. 다른 태그는 이 내부에서 정의되어야 하며, 대부분 반복 가능. 옵션. 순서무관. krpano 내부에 krpano 를 정의할 수도 있음(krpano scope에 세팅을 설정하기 위함) 여러번 선언되면 맨 마지막이 덮어씀.

참고 : 일부 노드와 속성은 특별하게 취급됨

• name attribute : xml 노드에 name이 있으면, 이 노드는 배열의 요소로 해석됨. 즉, 그 xml 노드가 또 있으며, 각 요소는 이름으로 구분된다는 뜻. 배열의 이름이 xml노드의 이름이 됨. 이름은 영문자로 시작해야함. 숫자로 시작하면 안됨. case insensitive.
• device attribute : xml 노드가 사용될 기기. all/flash/html5/mobile/tablet/iphone 등. 해당되지 않으면 통째로 무시됨.  | OR, + AND, !NOT 으로 묶을 수 있음.
• include node : 다른 xml 파일을 읽어들임. parsing 작업 전에 모든 include 노드를 대체함. 이 과정에서 url은 조정이됨. 아래 참조.
• <action>/<data>/<scene> xml 파싱동안에는 무시되고 content 변수에 별도 저장됨. 
• url attribute : xml 파일의 위치에 대한 상대경로로 인식됨. included xml의 url도 마찬가지임.

%FIRSTXML% - 최초에 불려진 xml 의 경로

%CURRENTXML% - 현재 xml 파일의 경로 (included xml의 path가 아님??)

%SWFPATH% - 

%HTMLPATH% - 

%BASEDIR% - Use the basedir path. ?? - default 는 %FIRSTXML%

%$VARIABLE% - 'VARIABLE'의 값. 현재의 xml 이나 scene이 로드되기전 정의되어있어야 함.

XML 노드/속성/속성값/변수

• <krpano version="1.0.8.15" onstart=""> ... </krpano>: onstart는 파노라마 뷰잉 시작때 적용할 action/function.
• <include url="~~.xml" /> 불러오는 파일로 대체됨. url은 조정됨
• <preview url="~~.jpg" /> 되도록이면 크기가 적은파일. kmakepreview 로 제작가능. 일부만 사용할 경우에는 hfov/vfov/voffset 을 사용하여 지정.
• <image>  <cube url="pano_%s.jpg" /> </image> 여기에서 %s는 l,f,r,b,u,d 을 의미함.

    <image> <cubestrip url="cubestrip.jpg"> </image>

    <image> <sphere url="pano.jpg"> </image>

    <image> <cylinder url="pano.jpg"> </image>

    <image type="cylinder" hfov="1.0"> <cylinder url="image.jpg"> </image> : FLAT 사진. 반드시 1.0

    <image> <qtvr url="quicktime.mov"> </image> QuickTime Movie

    <plugin name="video" url="videoplayer.swf" videourl="..." /> : 비디오일 경우 정의

         <image> <cylinder url="plugin:video" /> </image>

    full spherical 이 아닐 경우, hfov=360/vfov/voffset 사용하여 지정

이미지피라미드를 구성할 때 (Cube, multires)

<image type="CUBE"

       multires="true"   /*여기가 true이면, level이 여러개 있어야 함 */

       multiresthreshold="0.025" /* 어떤 레벨에서 다음 레벨로 넘어갈때의 임계치 */

       progressive="true" /* 저해상도부터 고해상도로 차례로 로드.

       tilesize="..."         /* 타일의 크기*/

       baseindex="1"      /* 타일 인덱스 시작번호 */

       frames="1"           /* 프레임의 수, 동일한 장면에 여러개의 프레임 가능*/

       frame="1"             /* 현재 프레임 */

       prealign=""           /* 회전인자 잘못된 것 수정 */

 >

  <level tiledimagewidth="..."  /*현재 레벨의 이미지 크기 */

         tiledimageheight="..."

         details="" 

         download="auto" decode="auto"  /* 현재 레벨 전체를 미리 다운로드 받아둘까? */

         aspreview="false"     /* 이 레벨을 프리뷰로 사용. true 이면 이레벨 전체가 다운로드됨 */

   >

    <cube url="pano_%s_%v_%u.jpg" />

  </level>

  <level ...>

    ...

  </level>

  ...

</image>

• <view hlookat="0.0" vlookat="0.0"  /* -180부터 180. -90부터 90. */

          fov="90.0"                         /* 현재의 fov */

          fovmin="1.0" fovmax="179.0"   /* 어디까지 확대/축소 가능한가 */

          maxpixelzoom="" />          /* fovmin 대신 사용가능. 1.0이면 픽셀 1:1임 */

• <area ....> 파노라마가 표시될 윈도의 범위. align 모드(크기와 위치)와 border 모드(경계선의 두께)가 있음. 참고 : 모든 layer/plugin 이 이 범위내에 그려짐. 바깥쪽에도 그리고 싶다면 layer/plugin 의 속성 parent="STAGE"로 지정해야함.

• <display> 렌더링 속도/성능과 관련된 설정. Flash 모드와 HTML5모드.
• <control> 마우스/키보드 세팅
• <cursors> 마우스 커서의 모양
• <autorotate enable="false"   
  

                 waittime="1.5"       /* 대기시간(초) */

                 speed="10.0" />   /* 회전속도 (도/초). 음수일때는 왼쪽으로 회전 */

• <layer>/<plugin> 은 사진, 로고, 버튼, 동적플러그인(krpano plugin) 등을 포함시킬 때 사용함. 여러개의 레이어/플러그인을 조합/적층 시킬 때에는 parent 설정을 사용하는 방법과, child xml 요소로서 children <layer>/<plugin> 요소를 정의하는 방법이 있음?? 이 경우, parent와 keep 은 자동적으로 parent 요소로 지정됨. <layer>와 <plugin>은 이름만 다를 뿐, 내부적으로는 완전히 동일.

<plugin name="..."   

        type="image"   /* image 또는 container. */

        url="..."          /* SWF, JPG, PNG, GIF */

        keep="false"   /* 새로운 pano 부를 때 유지시킬 것인지? */

        devices="all"

        visible="true"  /* 보이게 할 것인지. 동적으로 바꿀 수 있을 듯 */

        enabled="true"   /* 마우스 이벤트를 받을 것인지. false이면 아래로 통과 */

        handcursor="true"   /* 플러그인 위에 있을 때 핸드커서를 보이게 할 것인지 */

        zorder=""       /* 순서 html5에서는 0-100 */

        style=""     /* 공통스타일 사용. <style name="s1" alpha="0.5", scale="0.5> ... <plugin name="p1" style="s1"> <plugin name="p2" style="s1">...

        align=""   /* 스크린기준위치 lefttop, left, leftbottom, top, center, bottom, righttop, right, rightbottom */

        edge=""  /* plugin 이미지의 기준위치. */

        x=""  y=""    rotate="" /* 기준 위치간의 거리. %도 가능 */

        width=""   height=""     scale="1.0"  /* 지정하지 않으면 원본크기. height="prop" : 비율유지 */

        alpha="1.0"   /* 투명도. 0.0=완전투명. 1.0 불투명 */

        crop=""   onovercrop=""    ondowncrop=""  /*  crop="x-pos|y-pos|widht|height" */

        bgcolor="0x000000"        bgalpha="0.0"        bgcapture="false"

        parent=""       /* 현재의 plugin을 다른 plugin의 자식으로 지정함. 이렇게 되면 parent 요소를 기준으로 정렬됨. "STAGE"로 지정하면 현재 plugin이 파노라마를 벗어난 곳에도 나타남 */

        onover=""  onhover=""   onout=""   onclick=""     ondown=""   onup=""   onloaded="" /* function 또는 action */

        />

• <hotspot> 파노라마 영역중 마우스에 반응하는 지역. 다른 파노라마 불러오기, url로 연결하기, 뷰 바꾸기 등등 가능. polygonal/image 등 두가지가 있음. url을 지정하면 image, url 없고 좌표가 있으면 polygonal.

    <hotspot name="..."     url="..."     alturl="..."      keep="false"      devices="all"      visible="true"    

         enabled="true"        handcursor="true"         zorder=""         style=""

         ath="0.0" atv="0.0"  edge="center"  /* 핫스팟의 위치 (각도) 이 위치에 edge를 기준으로 정렬됨 */

         zoom="false"    /* 이미지 확대/축소에 따라 핫스팟 크기도 변하는지? */

         distorted="false" rx="0.0" ry="0.0" rz="0.0" 

         width="" height=""     scale="1.0"    rotate="0.0"    alpha="1.0"

         onover=""  onhover=""   onout=""   onclick=""     ondown=""   onup=""   onloaded="" 

         />

    <hotspot name="..."     keep="false"      visible="true"      enabled="true"      handcursor="true"      

         zorder=""     style=""     alpha="1.0"

         fillcolor="0xFFFFFF" fillcolorhover="0xFFFFFF" 

         fillalpha="0.0" fillalphahover="0.1"

         borderwidth="0.0" borderwidthhover="4.0"

         bordercolor="0xFFFFFF" bordercolorhover="0xFFFFFF"

         borderalpha="0.0" borderalphahover="0.8"

         onover=""  onhover=""   onout=""   onclick=""     ondown=""   onup="" 

    >

    <point ath="..." atv="..." />

    <point ath="..." atv="..." />

    <point ath="..." atv="..." />

    ...

    </hotspot>

• <style name="" .....> /* 핫스팟이나 플러그인에서 사용되는 모든 요소를 정의 가능 */
  

• <events> 어떤 특정 이벤트발생시 action / function 수행. name=""을 부여하지 않으면 global event가 된다. global event 는 단 하나. 따라서 또다시 정의하면 예전 정의는 사라짐. 새로운 xml, scene을 부르더라도 남아있음. name을 부여하면 독립적인 event가 됨. global event 다음에 호출됨. named event를 사용하면 다른 플러그인이나 xml코드와 간섭받지 않고 수행가능.??

    <events onenterfullscreen="",    onexitfullscreen=""   onxmlcomplete=""   onpreviewcomplete=""

        onloadcomplete=""   onnewpano=""   onremovepano=""   onloaderror=""   onkeydown=""

        onkeyup=""   onclick=""   onmousedown=""   onmouseup=""   onmousewheel=""   onidle=""

        onviewchange=""   onviewchanged=""    onresize=""

        />

• <action> krpano action 정의. action은 이벤트에서 호출되거나, 다른 actions 이나 외부(Javascript/Plugins)에서 call()하면 부를 수 있음. plugin/hotspot 이벤트에서도 호출. <action> 내에 action()을 여러개 호출 가능. 매개변수 전달 가능. 문자열로 전달. placeholder가 대체됨. %0%은 함수명, %1%은 첫번째 파라미터 등

   <action name="...">    action1(); action2();  ... </action>

• <scene>을 이용하면 하나의 xml 파일속에 여러장의 파노라마를 정의할 수 있음. <scene> 속에는 full krpano xml tree를 저장할 수 있음. 외부 xml 파일을 embed하는 것이라고 생각할 수 있음. loadscene()이 호출될 때야 비로서 파싱됨. 

    <scene name="..." onstart="">... </scene>