Dense Skeleton Image Coding
============================

(M. van der Zwan, Y. Meiburg, A. Telea)


1. Overview
============

This software tool implements the dense skeleton image coding technique described in the paper:

A Dense Medial Descriptor for Image Analysis (M. van der Zwan, Y. Meiburg, A. Telea Proc. VISAPP, INSTICC Press, 2013, pp. 342-351)

For technical details on how the method works, we refer to the paper above.


2. Prerequisites
=================

The software was compiled and tested on a Mac OS X 10.6.8 platform. It should run without problems on compatible Mac platforms.



3. Operation
=============

The software consists of two programs: A tool for converting grayscale PGM images into a dense-skeleton description, and a tool for processing such descriptions. These are described below.



3.1. Dense skeleton decription computation
===========================================

This operation is done by the tool 'imConvert'. The tool can be run as

imConvert <specification.conf>

Here, specification.conf is a simple ASCII file that describes the image to process, processing parameters, and where to output the description.
An example of such a file is given below, to illustrate the parameter meanings.

# Input file (make sure it is a binary PGM): 
filename = path_to_input_image.pgm

# Output level: Gives the amount of information displayed during the tool execution. 
# Values can be: {q,e,n,v}, meaning quiet, errors only, normal, verbose 
outputLevel = n 

# Layer	threshold: Float value in [0,1]. Controls in how many layers we decompose the image. 
lThreshold = 0.0001 

# Small object threshold, positive integer value. Gives the area of the smallest components
# we want to encode in a layer. 
sThreshold = 20 

# Skeleton distance	transform threshold, positive integer value. Gives the amount of simplification
# done to the layer skeletons, prior to any other operations. Good values range in [5..30]. 
#  Larger values simplify skeletons more.
sdtThreshold = 3 

# Skeleton saliency threshold, floating point value. Gives the amount of simplification done to
# layer skeletons, using the saliency metric described in the paper. Larger values cut off more
# non-salient branches.
ssThreshold = 2.0 

# Skeleton small object removal threshold. Obsolete, set to 0.
siThreshold = 0 

# Minimal object size 
minObjSize = 5 

# Unimportant object threshold 
minSumRadius = 25 

# Minimal path length threshold 
minPathLength = 10 

# Output file: Name of the file into which the output will be saved. This file should have the .sir extension. 
outputFile = path_to_output_file.sir




3.2. Dense skeleton image processing
=====================================

After a .sir file is computed from an imput image using imConvert, use the program 'imShow' to analyze or segment the image. For this, run

imShow <file.sir>

where file.sir is an output created earlier by imConvert.

By default, imShow shows a full reconstruction of the image which was encoded into the .sir file. 



4. Examples
============

A few sample images, configuration files, and computed skeletal descriptors are available in the input/ and output/ folders.


