From e644dd59f9dfee4064c4bb4e64dae09f385adef2 Mon Sep 17 00:00:00 2001 From: Personal-Desktop Date: Sun, 10 Nov 2019 00:50:55 +0100 Subject: [PATCH] Readme file and Help messages. --- README.md | 26 +++-- ShapeDatabase-UI/Console/Verbs/ModeOptions.cs | 102 +++++++++++++++++- 2 files changed, 117 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index d92ed21..05bb166 100644 --- a/README.md +++ b/README.md @@ -4,33 +4,45 @@ A content-based 3D shape retrieval system that, given a 3D shape, finds the most ## Purpose -Explain why this repository exists. +This program was originally constructed for the Multimedia Retrieval course from the University of Utrecht, Game and Media master classes. The point of the assignment was to build a content-based 3D shape retrieval system that, given a 3D shape, finds the most similar shapes in a given 3D shape database. This would teach us the following skills while making the progam: +- Build up practical skills in choosing, customizing, and applying specific techniques and algorithms to construct a realistic end-to-end MR system; +- Learn the pro's and con's of different techniques, and also subtle practical constraints these have, such as robustness, ease of use, and computational scalability; +- Make concrete design and implementation choices based on real-world output created by their system; +- Get exposed to all steps of the MR pipeline (data representation, cleaning, feature extraction, matching, evaluation, and presentation); ## Workings -Explain how it does what it does. +For more details on the inner workins of this program we would like to redirect you to the paper Building a content-based3D shape retrieval system by K.J.J. WesterBaan and G. de Jonge. ## Getting Started -Explain how you can use the application. +The program has all its interaction with the console, it is advised to call the application's .exe file through a console or batch file as well for easier usage. Some premade batch files are present in the application "Prepared Statements" folder and these also show insights in how you can configure your personal call to the program. If this is not clear than you can call the application with the help verb to get more information on how it can be used. "ShapeDatabase.exe help" ### Prerequisites -Explain the needed items before you download this project. +A good understanding of C# and Visual Studio is required to code for this program. ### Installing -Explain how to install this application for use. +There are 2 ways to use the application: One is to go to the releases section and download the database fully set-up and configured including .ini file weights; The other one is to clone this repository and build it manually with visual studio. The downside of this second approach is that the calculated weights from the .ini file are not present so you can figure these out on your own. For more information on how to clone a github repository check out the [Visual Studio Github tutorial](https://github.com/github/VisualStudio/blob/master/docs/using/cloning-a-repository-to-visual-studio.md) ## Build With -Explain the different packages which are used in this program. +This program wasn't possible without the following public packages from authors around Github. +- *Accord.Net:* for their statistical data processing, in particular their PCA system. +- *Geometry3Sharp:* for their 3D mesh computational algorithms. +- *HNSW.Net:* for their approximate neirest neighbour search program. +- *OpenTK:* for their visualisation code in C#. +- *CommandLineParser:* for easier console usage. +- *CsvHelper:* for their Csv reader and writers. +- *IniParser:* for their ini readers and writers. ## Contributors / Authors The people who made this original repository and brought this code to the world were: - @kevin4998 + - @guusdejonge ## Acknolwedgements -Show who helped us in creating this project. \ No newline at end of file +And finally we would like to thank all the public library authors who made it possible for us to construct this program, the C# team for this programming language and our professor prof. dr. Alexandru C. Telea for teaching us how to design such an extensive system. \ No newline at end of file diff --git a/ShapeDatabase-UI/Console/Verbs/ModeOptions.cs b/ShapeDatabase-UI/Console/Verbs/ModeOptions.cs index 4427cda..a2193ac 100644 --- a/ShapeDatabase-UI/Console/Verbs/ModeOptions.cs +++ b/ShapeDatabase-UI/Console/Verbs/ModeOptions.cs @@ -1,5 +1,6 @@ using System.Collections.Generic; using CommandLine; +using CommandLine.Text; namespace ShapeDatabase.UI.Console.Verbs { @@ -18,31 +19,99 @@ public class CleanOptions : BaseOptions { HelpText = "If the settings file should be cleaned.")] public bool CleanSettings { get; set; } + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("Clean the application including settings files.", new CleanOptions() { CleanSettings = true }); + yield return new Example("Clean the application excluding settings files.", new CleanOptions() { CleanSettings = false }); + yield return new Example("Clean the application and continue.", new CleanOptions() { CleanSettings = false, AutoExit = true, DebugMessages = true }); + } + } + } /// /// The options to display a collection of shapes to the user. /// [Verb("view", HelpText = "View the different Shapes in the system.")] - public class ViewOptions : ShapeOptions { } + public class ViewOptions : ShapeOptions { + + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("View the unrefined demo files.", new ViewOptions() { ShapeDirectories = new string[] { "Content/Shapes/Demo" } }); + yield return new Example("View the unrefined small files.", new ViewOptions() { ShapeDirectories = new string[] { "Content/Shapes/Small" } }); + yield return new Example("View the previously refined files.", new ViewOptions() { }); + } + } + + } /// /// The options to refine a collection of shapes for the user. /// [Verb("refine", HelpText = "Refine provided shapes and stores them in the system.")] - public class RefineOptions : ShapeOptions { } + public class RefineOptions : ShapeOptions { + + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("Refine all the files in the demo map, overwriting existing ones.", + new RefineOptions() { ShapeDirectories = new string[] { "Content/Shapes/Demo" }, Overwrite = true }); + yield return new Example("Refine all the files in the all map.", new RefineOptions() { ShapeDirectories = new string[] { "Content/Shapes/All" } }); + } + } + + } /// /// The options to calculate metrics for the current shapes. /// [Verb("measure", HelpText = "Calculate metrics for all the current shapes.")] - public class MeasureOptions : ShapeOptions { } + public class MeasureOptions : ShapeOptions { + + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("Measure the unrefined files in the Demo directory, overwriting refined variants.", + new MeasureOptions() { ShapeDirectories = new string[] { "Content/Shapes/Demo" }, Overwrite = true }); + yield return new Example("Measure all the refined files.", new MeasureOptions() { }); + } + } + + } /// /// The options to calculate features for the current shapes for comparison. /// [Verb("feature", HelpText = "Calculate features for all the current shapes.")] - public class FeatureOptions : CalculateOptions { } + public class FeatureOptions : CalculateOptions { + + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("Calculate the features from the refined files and exit the application.", + new FeatureOptions() { AutoExit = true }); + yield return new Example("Calculate the features from the refined files but do not save it.", new FeatureOptions() { Export = false }); + } + } + + } /// /// The options to compare shapes for similarity. @@ -101,6 +170,18 @@ public bool HasDirectories { HelpText = "The mode which is used to determine the query size.")] public string QuerySize { get; set; } + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("Compare all the items in the database with each other with the query size being the size of the class.", + new QueryOptions() { AutoExit = true, QueryInput = "internal", QuerySize = "class" }); + yield return new Example("Compare with items from the query folder returning the amount of items as specified in the settings.ini file.", + new QueryOptions() { AutoExit = true, QueryInput = "refine", QuerySize = "kbest" }); + } + } } @@ -124,6 +205,19 @@ public class EvaluateOptions : CalculateOptions { HelpText = "The mode which is used to determine the outputed query results.")] public string Evaluation { get; set; } + /// + /// Display help information on how to use this verb. + /// + [Usage] + public static IEnumerable Examples { + get { + yield return new Example("Evaluate the last query results showing the metrics for each individual file.", + new EvaluateOptions() { AutoExit = true, Evaluation = "individual" }); + yield return new Example("Evaluate the last query results showing the metrics per class.", + new EvaluateOptions() { AutoExit = true, Evaluation = "aggregated" }); + } + } + } }