Doxygen Intergration in Visual Studio 2010 Environment

When the source code package is huge including more than 2000 files and each may have > 10,000 lines of code, it is a good idea to generate some documents using doxygen. “Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.” (webpage), it works out of the box on Linux/UNIX. For windows under Visual studio environment, some extra settings are needed. Here are the steps:

1. Download the Win32 binaries here and install them. For example, you installed doxygen in c:program filesdoxygen.
2. Create a doxygen configuration file and save it as default.doxygen under the same folder as the project. Notice that to generate graphical representation of class hierachy, you need to install graphivz (link). Here is the one I used.

# Doxyfile 1.8.2

#---------------------------------------------------------------------------
# Project related configuration options
#---------------------------------------------------------------------------
DOXYFILE_ENCODING      = UTF-8
PROJECT_NAME           = "InSite"
PROJECT_NUMBER         = 2.16
OUTPUT_DIRECTORY       =
CREATE_SUBDIRS         = NO
OUTPUT_LANGUAGE        = English
BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
ABBREVIATE_BRIEF       = "The $name class" 
 "The $name widget" 
 "The $name file" 
 is 
 provides 
 specifies 
 contains 
 represents 
 a 
 an 
 the
ALWAYS_DETAILED_SEC    = NO
INLINE_INHERITED_MEMB  = NO
FULL_PATH_NAMES        = YES
STRIP_FROM_PATH        =
STRIP_FROM_INC_PATH    =
SHORT_NAMES            = NO
JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS           = YES
SEPARATE_MEMBER_PAGES  = NO
TAB_SIZE               = 8
ALIASES                =
OPTIMIZE_OUTPUT_FOR_C  = NO
OPTIMIZE_OUTPUT_JAVA   = NO
OPTIMIZE_FOR_FORTRAN   = NO
OPTIMIZE_OUTPUT_VHDL   = NO
BUILTIN_STL_SUPPORT    = NO
CPP_CLI_SUPPORT        = YES
SIP_SUPPORT            = NO
IDL_PROPERTY_SUPPORT   = YES
DISTRIBUTE_GROUP_DOC   = NO
SUBGROUPING            = YES
TYPEDEF_HIDES_STRUCT   = NO
SYMBOL_CACHE_SIZE      = 0
#---------------------------------------------------------------------------
# Build related configuration options
#---------------------------------------------------------------------------
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = YES
EXTRACT_ANON_NSPACES   = YES
HIDE_UNDOC_MEMBERS     = NO
HIDE_UNDOC_CLASSES     = NO
HIDE_FRIEND_COMPOUNDS  = NO
HIDE_IN_BODY_DOCS      = NO
INTERNAL_DOCS          = NO
CASE_SENSE_NAMES       = YES
HIDE_SCOPE_NAMES       = NO
SHOW_INCLUDE_FILES     = YES
INLINE_INFO            = YES
SORT_MEMBER_DOCS       = YES
SORT_BRIEF_DOCS        = NO
SORT_GROUP_NAMES       = NO
SORT_BY_SCOPE_NAME     = NO
GENERATE_TODOLIST      = YES
GENERATE_TESTLIST      = YES
GENERATE_BUGLIST       = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS       =
MAX_INITIALIZER_LINES  = 30
SHOW_USED_FILES        = YES
SHOW_DIRECTORIES       = NO
SHOW_FILES             = YES
SHOW_NAMESPACES        = YES
FILE_VERSION_FILTER    =
LAYOUT_FILE            =
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET                  = NO
WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = NO
WARN_FORMAT            = "$file:$line: $text"
WARN_LOGFILE           =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT                  = .
INPUT_ENCODING         = UTF-8
FILE_PATTERNS          = *.c 
 *.cc 
 *.cxx 
 *.cpp 
 *.c++ 
 *.d 
 *.java 
 *.ii 
 *.ixx 
 *.ipp 
 *.i++ 
 *.inl 
 *.h 
 *.hh 
 *.hxx 
 *.hpp 
 *.h++ 
 *.idl 
 *.odl 
 *.cs 
 *.php 
 *.php3 
 *.inc 
 *.m 
 *.mm 
 *.dox 
 *.py 
 *.f90 
 *.f 
 *.vhd 
 *.vhdl
RECURSIVE              = YES
EXCLUDE                =
EXCLUDE_SYMLINKS       = NO
EXCLUDE_PATTERNS       =
EXCLUDE_SYMBOLS        =
EXAMPLE_PATH           =
EXAMPLE_PATTERNS       = *
EXAMPLE_RECURSIVE      = NO
IMAGE_PATH             =
INPUT_FILTER           =
FILTER_PATTERNS        =
FILTER_SOURCE_FILES    = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER         = YES
INLINE_SOURCES         = YES
STRIP_CODE_COMMENTS    = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
REFERENCES_LINK_SOURCE = YES
USE_HTAGS              = NO
VERBATIM_HEADERS       = YES
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
COLS_IN_ALPHA_INDEX    = 5
IGNORE_PREFIX          =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML          = YES
HTML_OUTPUT            = html
HTML_FILE_EXTENSION    = .html
HTML_HEADER            =
HTML_FOOTER            =
HTML_STYLESHEET        =
HTML_ALIGN_MEMBERS     = YES
HTML_DYNAMIC_SECTIONS  = NO
GENERATE_DOCSET        = NO
DOCSET_FEEDNAME        = "Doxygen generated docs"
DOCSET_BUNDLE_ID       = org.doxygen.Project
GENERATE_HTMLHELP      = NO
CHM_FILE               =
HHC_LOCATION           =
GENERATE_CHI           = NO
CHM_INDEX_ENCODING     =
BINARY_TOC             = NO
TOC_EXPAND             = NO
GENERATE_QHP           = NO
QCH_FILE               =
QHP_NAMESPACE          = org.doxygen.Project
QHP_VIRTUAL_FOLDER     = doc
QHG_LOCATION           =
DISABLE_INDEX          = NO
ENUM_VALUES_PER_LINE   = 4
GENERATE_TREEVIEW      = ALL
TREEVIEW_WIDTH         = 250
FORMULA_FONTSIZE       = 10
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX         = NO
LATEX_OUTPUT           = latex
LATEX_CMD_NAME         = latex
MAKEINDEX_CMD_NAME     = makeindex
COMPACT_LATEX          = NO
PAPER_TYPE             = a4wide
EXTRA_PACKAGES         =
LATEX_HEADER           =
PDF_HYPERLINKS         = YES
USE_PDFLATEX           = YES
LATEX_BATCHMODE        = NO
LATEX_HIDE_INDICES     = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF           = NO
RTF_OUTPUT             = rtf
COMPACT_RTF            = NO
RTF_HYPERLINKS         = NO
RTF_STYLESHEET_FILE    =
RTF_EXTENSIONS_FILE    =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN           = NO
MAN_OUTPUT             = man
MAN_EXTENSION          = .3
MAN_LINKS              = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML           = NO
XML_OUTPUT             = xml
XML_SCHEMA             =
XML_DTD                =
XML_PROGRAMLISTING     = YES
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF   = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD       = NO
PERLMOD_LATEX          = NO
PERLMOD_PRETTY         = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = NO
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES
INCLUDE_PATH           =
INCLUDE_FILE_PATTERNS  =
PREDEFINED             =
EXPAND_AS_DEFINED      =
SKIP_FUNCTION_MACROS   = YES
#---------------------------------------------------------------------------
# Configuration::additions related to external references
#---------------------------------------------------------------------------
TAGFILES               =
GENERATE_TAGFILE       =
ALLEXTERNALS           = NO
EXTERNAL_GROUPS        = YES
PERL_PATH              = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS         = YES
MSCGEN_PATH            =
HIDE_UNDOC_RELATIONS   = YES
HAVE_DOT               = YES
DOT_FONTNAME           = FreeSans
DOT_FONTPATH           =
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
GROUP_GRAPHS           = YES
UML_LOOK               = YES
TEMPLATE_RELATIONS     = YES
INCLUDE_GRAPH          = YES
INCLUDED_BY_GRAPH      = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
GRAPHICAL_HIERARCHY    = YES
DIRECTORY_GRAPH        = YES
DOT_IMAGE_FORMAT       = png
DOT_PATH               = "C:Program Files (x86)Graphviz 2.28bindot.exe"
DOTFILE_DIRS           =
DOT_GRAPH_MAX_NODES    = 50
MAX_DOT_GRAPH_DEPTH    = 1000
DOT_TRANSPARENT        = YES
DOT_MULTI_TARGETS      = YES
GENERATE_LEGEND        = YES
DOT_CLEANUP            = YES
#---------------------------------------------------------------------------
# Configuration::additions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE           = YES

3. Add a new custom tool, called “DoxyGen”, with the following parameters:
Command: c:program filesdoxygenbindoxygen.exe (or where you installed it)
Arguments: “$(ItemDir)default.doxygen” (the config file – including the quotes)
Initial Directory: $(ItemDir)
Check the “Use the output window” box
4. Add another tool, to view the results new “View DoxyDoc” tool, to view the results:
Command your favorite browser, e.g. C:Program Files (x86)Mozilla Firefoxfirefox.exe
Arguments: “$(ItemDir)htmlindex.html” (including the quotes)
Initial Directory: leave empty
5. Under the solution view, right click the project and select “Add”->”Existing Item…” and in the pop-up window select default.doxygen under your project folder. Open it for editing in VC++, and Change the PROJECT_NAME and the PROJECT_NUMBER to match your project.
6. Choose Tools/doxygen from the menu, and watch the output dump into the Output window of visual studio. Once finished, check for any error messages.
7. You are done! Use Tool->View DoxyDoc to open the index.html file.

Doxygen in Visual Studio 2010

Doxygen in Visual Studio 2010


This article was inspired by this blog (link).

Tracing the rays without ray tracing

Seismic ray tracing has many applications and the essential information we try to get from ray tracing is the traveltime. In mining, (time lapsed) traveltime tomography gives a quick and good enough information about velocity structure within the rock. So you can tell where the damage has occurred and where the orebody is located, etc. In mining and in petroleum, automated micro-earthquake locating is a hot topic. You can see (or listen) where the fractures are propagating. However, ray tracing is not easy; it is nonlinear and the first arrival travel time field is not smooth, i.e., even the first order gradient doesn’t exist everywhere.

I propose an alternative method to get the traveltime without tracing the rays: fast sweeping method, a type of finite different method to solve the eikonal equation for traveltime field. It works on tetrahedral elements as well and can handle anisotropic velocity.

Actually there is more information you can get when doing the old school ray tracing, i.e.,the incident angle, the emerging angle, and the traveling distance. This info is not available after solving the eikonal equation but as byproduct after the ray tracing. How to cope with that? Reverse tracing the rays from arbitrary point other than the source point back to the source point is the solution. Here is how:

(1) solve the Eikonal equation
(2) choose the receiver location as the ray initial point
(3) trace the ray backwards using the travel time field till it reaches the element where the source is located.
(4) since the ray path is available, incident angle, emerging angle, and traveling distance can be obtained. Done.

Here is the results:

3D ray tracing based on the first arrival traveltime field

3D ray tracing based on the first arrival traveltime field. The red dot is the source and red lines shows the rays from the source to the receivers.


Here is the ray skeleton (without the isosurface). It shows direct arrivals, head wave arrivals and refraction arrivals:
3D ray tracing based on the first arrival traveltime field

3D ray tracing based on the first arrival traveltime field. The red dot is the source and the red lines are the rays. The black dots are the location of receivers.