SINAMIS Is Not A Mesh Indexing System

Julien Tierny, Jean-Philippe Vandeborre and Mohamed Daoudi

Benchmarking tools and partial 3D shape retrieval system

Foreword

This package contains benchmarking tools for partial 3D shape retrieval system evaluation along with a partial 3D shape retrieval system that implements the method described in the paper Partial 3D shape retrieval by Reeb pattern unfolding [4].
Before downloading the package, to keep track of its distribution, we would be very grateful if you could acknowledge us your download by email: julien dot tierny at telecom-lille1 dot eu.
If you ever exploit experimental results obtained with this package in a scientific publication, please reference the following paper: Partial 3D shape retrieval by Reeb pattern unfolding [4].

Download SINAMIS package

System requirements

Operating system

SINAMIS is entirely written in C and is only released as a binary version, compiled for GNU/Linux systems (with gcc 4.1.2) running on i386 like CPUs.

Third party libraries

SINAMIS runs on top of two third party libraries:
- GNU Scientific Library (libgsl):

	Required version: 1.9
	GSL project homepage
	Installation: please refer to the package management system of your GNU/Linux distribution.

- GNU Triangulated Surface (libgts):

	Required version: 0.7.6
	GTS project homepage
	Installation: please refer to the package management system of your GNU/Linux distribution.

Package content

bin/ directory

- ndcg: NDCG score computation program.
- sinamis: Partial 3D shape retrieval system (see paper Partial 3D shape retrieval by Reeb pattern unfolding).
- wrl2gts: WRL to GTS file format convertor.

data/ directory

- shrec07_cornea_ndcg.plot: NDCG vector score of [2] on SHREC 2007 partial matching track data-set (extracted from [3]).
- shrec07_dataset_rpu.idx: SHREC 2007 partial matching track data-set index file generated with [4].
- shrec07_erg_ndcg.plot: NDCG vector score of [1] on SHREC 2007 partial matching track data-set (extracted from [3]).
- shrec07_groundtruth.txt: SHREC 2007 partial matching track query-set ground-truth (see [3]).
- shrec07_rpu_ndcg.plot: NDCG vector score of [4] on SHREC 2007 partial matching track data-set (see [3]).
- shrec07_rpu_score.txt: Matrix score file generated with [4] on SHREC 2007 partial matching track query-set (see [3]).

scripts/ directory

- index.sh: Bourne-shell script for data-set off-line indexing with SINAMIS [4].
- scores.sh: Bourne-shell script for query-set matrix score file generation with SINAMIS [4].

Data-sets

SINAMIS package comes with no data-set! SHREC 2007 data and query sets are courtesy of AIM@SHAPE.

SHREC 2007 partial matching track data-set

Performance evaluation reported in [4] has been achieved on the SHREC 2007 partial matching track query and data sets.
This data-set is a pre-classified collection of 400 manifold meshes. It exhibits diverse geometry (pose change) and topology variations within classes.
The query-set is composed of 30 manifold meshes. Each of them shares visually similar sub-parts with at least two classes of the data-set.
SHREC 2007 data and query sets are courtesy of AIM@SHAPE.

Other data-sets

SINAMIS package provides sufficient softwares and data samples to extend experiments to any other data-set. All you need to have is a pre-classified data-set, a query-set sharing similar sub-parts with classes of the data-set and a query-set ground-truth (see below).
Please notice SINAMIS can only process closed manifold meshes.

Usage

Package decompression

Just un-compress the package tarball with the following command:

$ tar xvzf sinamis.tar.gz

In the rest of the document, we assume you only change directory to:

$ cd sinamis

Data conversion

SINAMIS partial 3D shape retrieval system (bin/sinamis) takes GTS files as an input. All data must be converted to GTS format first before using SINAMIS.
You will find a minimalist WRL to GTS mesh file format convertor in the bin directory. Example usage:

$ bin/wrl2gts mymesh.wrl

GTS meshes can be displayed with the mview software.

Classification, ground-truth and score matrices

Classification

In order to use SINAMIS NDCG score computation program (bin/ndcg), the filename of the data-set entries must begin with their class name in capital letters, followed by an underscore. Here are valid examples:

	ARMADILLO_dataset_entry127.gts
	ARMADILLO_127.wrl

Ground-truth

The ground-truth file is an ASCII file that lists for each query the sets of Highly Relevant (HR) and Marginally Relevant (MR) corresponding classes of the data-set as well as the total number of related data-set entries (please see [3] for more details about the NDCG vector computation).
If a query has no particular corresponding class, just use the keyword "NONE".
The format for query entries is the following (one line per query):

<QUERY_ID>;<TOTAL NUMBER FOR HR CLASSES>, <HR CLASS 1>, ... <HR CLASS n>; <TOTAL NUMBER FOR MR CLASSES>, <MR CLASS 1>, ... <MR CLASS n>

Here are valid examples:

	11;40,FISH,HAND;0,NONE
	19;40,PLANE,ARMADILLO;60,HUMAN,BIRD,PLIER
	30;40,FOUR,HUMAN;40,ARMADILLO,TEDDY

SINAMIS package already contains the ground-truth file for the SHREC 2007 partial matching query and data sets (data/shrec07_groundtruth.txt).

Score matrices

In order to use SINAMIS NDCG score computation program (bin/ndcg), your system must output ASCII score matrix files using the following format.
Each line of the score file must correspond to the same line of the ground-truth file (results for query appearing line 3 of the ground-truth file must appear at the third line).
Each line must contain the filename of the data-set entries sorted by decreasing similarity (top results first) separated by the ";" character.
SINAMIS package already contains the score matrix file on SHREC 2007 partial matching track query set, generated with the method described in [4] (data/shrec07_rpu_score.txt).

Off-line indexing

Indexing a whole data-set

The Bourne-shell script bin/index.sh allows you to easily index a data-set with SINAMIS. Please edit this file and fill the following variables (as indicated in the file):
- DATASET_PATH: directory containing your GTS data-set;
- SINAMIS_PATH: directory containing the sinamis binary;
- INDEX_FILE: name of the output index file.
Then, just run:

$ scripts/index.sh

... and go make some coffee :)

Indexing standalone entries

To append a new standalone entry to the index file, just:

$ bin/sinamis -i <INDEX FILE> -n <STANDALONE GTS ENTRY>

SINAMIS package already contains the index file generated with the method described in [4] for the SHREC 2007 partial matching track data-set (data/shrec07_dataset_rpu.idx).

On-line querying

To run a partial similarity query against an indexed data-set, just:

	$ bin/sinamis -i <INDEX FILE> -q <GTS QUERY>

Data-set entries will be displayed by increasing similarity (top results at the end).

NDCG score computation

To compute NDCG vector scores (see [3]), you will need a query-set ground-truth file and a score matrix (generated by the partial shape retrieval system) as described above.

Computing score files with SINAMIS

To compute a new score matrix file with SINAMIS, use the Bourne-shell script scripts/scores.sh. Please edit this file and fill the following variables (as indicated in the file):
- QUERYSET_PATH: directory containing your GTS query-set;
- SINAMIS_PATH: directory containing the sinamis binary;
- INDEX_FILE: full path to the data-set index file;
- SCORE_FILE: name of the output score file.
Then, just run:

	$ scripts/scores.sh

... and go make some coffee :)
SINAMIS package already contains the score file generated with the method described in [4] for the SHREC 2007 partial matching track data-set (data/shrec07_rpu_score.txt).

Computing NDCG vector files

To compute NDCG vector files (generated with SINAMIS or other systems), run:

	$ bin/ndcg -g <GROUND-TRUTH FILE> -s <SCORE FILE>

This command will output as many NDCG vector files as query-set entries plus a global NDCG which averages all the queries (see [3]). These plots can be displayed with a software like GNU Plot.

Examples

To reproduce the experimental results presented in the paper Partial 3D shape retrieval by Reeb pattern unfolding [4], run the following commands:
- Figure 13, page 8:

	$ bin/sinamis -i data/shrec07_dataset_rpu.idx -q <PATH TO SHREC 2007 QUERY 30 (GTS)>

- Figure 14, page 8:

	$ bin/sinamis -i data/shrec07_dataset_rpu.idx -q <PATH TO SHREC 2007 QUERY 21 (GTS)>

- Figure 15, page 9:

	$ bin/sinamis -i data/shrec07_dataset_rpu.idx -q <PATH TO SHREC 2007 QUERY 19 (GTS)>

- Figure 16, page 8:

	$ bin/ndcg -g data/shrec07_groundtruth.txt -s data/shrec07_rpu_score.txt

Then, you can view with GNU Plot the generated file NDCG.plot along with the NDCG vector files for the other methods [1][2] (respectively data/shrec07_erg_ndcg.plot and data/shrec07_cornea_ndcg.plot).

Bugs

Because sh*t happens, please feel free to send any bug report or comment to: julien dot tierny at telecom-lille1 dot eu.

References

[1] BIASOTTI S., MARINI S., SPAGNUOLO M., FALCIDIENO B.:
Sub-part correspondence by structural descriptors of 3D shapes. Computer-Aided Design Journal 38 (2006), pp. 1002-1019.
[2] CORNEA N. D., DEMIRCI M. F., SILVER D., SHOKOUFANDEH A., DICKINSON S., KANTOR P. B.:
3D object retrieval using many-to-many matching of curve skeletons. In IEEE Shape Modeling International (2005), pp. 366-371.
[3] MARINI S., PARABOSCHI L., BIASOTTI S.:
SHape REtrieval Contest 2007: Partial matching track. In SHREC (in conjunction with IEEE Shape Modeling International) (2007), pp. 13-16.
[4] Tierny J., Vandeborre J.-P., Daoudi M.:
Partial 3D shape retrieval by Reeb pattern unfolding. Computer Graphics Forum, To appear (2008).

>> Back to my research page

Updated on July 24th, 2008.