Documentation

Using Viking on your data

Viking is capable of displaying any correct formatted image data.
To use Viking for different images you need to create a VikingXML file,
which you can then pass to Viking on the command line or via a URL.
A Viking URL looks like this:

http://155.100.105.9/Software/Viking.Application?http://155.100.105.9/Rabbit/Volume.VikingXML

The string before the question mark tells the browser which application to launch.
The string after the question mark is the parameter and tells viking to load the VikingXML
file from that location. Viking does not support reading files from the local disk at this time.
Eventually this format will change, but we’ll try to support backward compatibility.

Python scripts that create VikingXML files by cutting single images into tilesets
or converting the output of the NCRToolset into VikingXML files are available on request.
Ultimately they will be replaced by Iris, the GUI interface to the NCRToolset.

The XML Schema Definition for VikingXML files is here: VikingXML.xsd Right-click or ctrl-click to download.

Viking has not been tested against a lot of different input and does not yet have robust error reporting.
We recommend testing after adding each element and not deviating too much from the sample below at first.
Please let Dr. James Anderson know if you encounter trouble (james.anderson at hsc.utah.edu).

Below is an example snippet of VikingXML which loads one section of our RC1 volume.
You can verify it works by pasting this address into your browser:

http://155.100.105.9/Software/Viking.Application?http://155.100.105.9/Demo.VikingXML

<?xml version=”1.0″?>
<Volume name=”Rabbit” UniqueID=”1″ num_stos=”340″ num_sections=”341″ path=”http://155.100.105.9/Rabbit”
xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:noNamespaceSchemaLocation=”http://connectome.utah.edu/VikingXML.xsd”>
<stos mappedSection=”2″ controlSection=”1″ pixelSpacing=”16″ type=”grid” path=”0002-0001_grid_16.stos”/>
<stos mappedSection=”3″ controlSection=”2″ pixelSpacing=”16″ type=”grid” path=”0003-0002_grid_16.stos”/>
<Section number=”30″ path=”0030″ >
<transform name=”0030_Supertile.mosaic” path=”0030_Supertile.mosaic” UseForVolume=”false” FilePrefix=”0030″ FilePostfix=”.png” />
<transform name=”grid.mosaic” path=”grid.mosaic” UseForVolume=”true” FilePrefix=”0030″ FilePostfix=”.png” />
<transform name=”translate.mosaic” path=”translate.mosaic” UseForVolume=”false” FilePrefix=”0030″ FilePostfix=”.png” />
<Pyramid name=”8-bit” path=”8-bit”>
<Level Downsample=”1″ path=”001″/>
<Level Downsample=”2″ path=”002″/>
<Level Downsample=”4″ path=”004″/>
<Level Downsample=”8″ path=”008″/>
<Level Downsample=”16″ path=”016″/>
<Level Downsample=”32″ path=”032″/>
<Level Downsample=”64″ path=”064″/>
</Pyramid>
<Tileset name=”mosaic” path=”mosaic” FilePrefix=”0030_” FilePostfix=”.png” TileXDim=”256″ TileYDim=”256″ >
<Level Downsample=”1″ GridDimX=”462″ GridDimY=”466″ path=”001″/>
<Level Downsample=”2″ GridDimX=”231″ GridDimY=”233″ path=”002″/>
<Level Downsample=”4″ GridDimX=”116″ GridDimY=”117″ path=”004″/>
<Level Downsample=”8″ GridDimX=”58″ GridDimY=”59″ path=”008″/>
<Level Downsample=”16″ GridDimX=”29″ GridDimY=”30″ path=”016″/>
<Level Downsample=”32″ GridDimX=”15″ GridDimY=”15″ path=”032″/>
<Level Downsample=”64″ GridDimX=”8″ GridDimY=”8″ path=”064″/>
</Tileset>
<Tileset name=”Glycine” path=”Glycine” FilePrefix=”” FilePostfix=”.png” TileXDim=”256″ TileYDim=”256″>
<Level GridDimX=”15″ GridDimY=”15″ Downsample=”32″ path=”032″/>
<Level GridDimX=”8″ GridDimY=”8″ Downsample=”64″ path=”064″/>
</Tileset>
<ChannelInfo>
<Channel Section=”Selected” Channel=”mosaic” Color=”0xFF00FF”/>
<Channel Section=”Selected” Channel=”Glycine” Color=”0x00FF00″/>
</ChannelInfo>
</Section>
</Volume>

VikingXML Element Documentation

VikingXML Element Documentation

Volume

<Volume name=”Rabbit” UniqueID=”1″ num_stos=”340″ num_sections=”341″ path=”http://155.100.105.9/Rabbit” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xsi:noNamespaceSchemaLocation=”http://connectome.utah.edu/VikingXML.xsd”>

Required element which contains all information about the volume and optionally points to the VikigXML schema definition.

  • Name: The name of the volume.
  • num_stos: Optional, the number of stos tags in the volume. Only used for loading progress bar and will eventually be removed.
  • num_sections: Optional, the number of section tags in the volume. Only used for loading progress bar and will eventually be removed.
  • path: Required, the URL of the root path of the volume. Only used when VikingXML is loaded from local disk.

stos

<stos mappedSection=”2″ controlSection=”1″ pixelSpacing=”16″ type=”grid” path=”0002-0001_grid_16.stos”/>

Optional element which defines a slice-to-slice transform (stos). These are used to tell Viking how to warp from section space to volume space. All attributes are required.

  • mappedSection: The section being transformed
  • controlSection: The section not being transformed
  • pixelSpacing: stos files are rarely generated against the full-resolution data. This value tells viking how much the coordinates should be scaled by to match the actual image dimensions.
  • type: The type of transform to use, currently always use “grid”.
  • path: Relative path from Volume path to the stos file containing transformation data.

Section

<Section number=”30″ path=”0030″ >

The section tag describes a slice in the volume at a specific z depth. If there are no section tags there are no images in the volume.

  • name: Friendly name of the section. Defaults to section number. I recommend using section number because I haven’t tested anything else.
  • number: Integer, numbers should be sequential according to the order in which sections were cut. It is OK to skip numbers for lost sections.
  • path: Relative path from Volume path to the Section directory.

Pyramid

<Pyramid name=”8-bit” path=”8-bit”>

Image pyramids are generated from the original images captured by an imaging platform.
We use these image pyramids with the NCRToolset to generate transforms that describe
where each tile in the pyramid is positioned in section space. In the pyramid each tile size
is variable according to its source pyramid level. This makes for poor performance over the internet
but is very useful for debugging the output of the NCRToolset over an intranet.

  • name: Name of the channel displayed in the Viking UI.
  • path: Relative path from the section path.

Transform

<transform name=”grid.mosaic” path=”grid.mosaic” UseForVolume=”true” FilePrefix=”0030″ FilePostfix=”.png” />

Transforms are only applied to Pyramids. They are generated by the NCRToolset
and describe how each tile in a mosaic is positioned in the section.

  • Name: Name of the transform in the Viking UI
  • path: Relative path from the section path.
  • UseForVolume: Boolean, specifies that this transform is used to position tiles in the section before the are warped into the volume. Only the highest quality transform should have this set.
  • FilePrefix: String to prepend to all file names, if needed. A period is added after the file prefix. Traditionally we prepend the section number to tile names. Tiles are expected to be numbered with three digits. i.e. Section 1 Tile 243 = 0001.243.png
  • FilePostfix: Extension to add to file names, must be supported by XNA library. .png format recommended.

Tileset

<Tileset name=”Glycine” path=”Glycine” FilePrefix=”” FilePostfix=”.png” TileXDim=”256″ TileYDim=”256″>

In a tileset all the images have a fixed size regardless of the level of the pyramid.
We typically use 256×256 pixel tiles laid out on a grid with no overlap. This optimizes
bandwidth use. Tile names include the grid position, i.e. X001_Y001.png

  • Name: Name of the channel displayed in the Viking UI
  • path: Relative path from the section path.
  • UseForVolume: Boolean, specifies that this transform is used to position tiles in the section before the are warped into the volume. Only the highest quality transform should have this set.
  • FilePrefix: String to prepend to all file names, if needed. A period is added after the file prefix. Traditionally we prepend the section number to tile names. Tiles are expected to be numbered with three digits. i.e. Section 1 Tile 243 = 0001.243.png
  • FilePostfix: Extension to add to file names, must be supported by XNA library. .png format recommended.
  • TileXDim: Pixel X dimensions of each tile
  • TileYDim: Pixel Y dimensions of each tile

Level

<Level Downsample=”1″ GridDimX=”462″ GridDimY=”466″ path=”001″/>

Describes a level in a “tileset” or “pyramid” image pyramid. A level is a directory containing all of the original tiles downsampled by a common factor.

    .

  • Level: A number defining what level of the pyramid this is. Must currently be a power of two.
  • path: Relative path from the tileset or pyramid path.
  • GridDimX: Tilesets only, Integer defining the dimensions of the grid in X
  • GridDimY: Tilesets only, Integer defining the dimensions of the grid in Y

ChannelInfo

<ChannelInfo>

Channel info is an optional element allowing volumes to define a default mix of channels for a section.
This element can also be placed under the volume element to define a global default channel setup.
Section channel configurations override volume channel configurations.

Channel

<Channel Section=”Selected” Channel=”Glycine” Color=”0x00FF00″/>

Specifies a channel to display by default.

  • Section: The section to load the channel from, must be one of these values: Defines which section to load a channel from:
    • “Selected”: Load images from the users currently selected section
    • “Fixed”: Load images from the specified section
    • “Above”: Load images from the reference section above the users selected section
    • “Below”: Load images from the reference section below the users selected section
  • Channel: The name of the channel, either a pyramid or tileset, to load, or “Selected” for user selected channel
  • Color: Color to use when displaying channel, specify as a web color i.e. #00ff00