Difference between revisions of "Deuces"

From BRL-CAD
(add template, remove translations)
(start of simplification, remove references and difficulty)
Line 4: Line 4:
  
 
Please do contact us (via [[IRC]] or [[Mailing_Lists|brlcad-devel mailing list]]) if you have any questions, corrections, comments, or ideas of your own that you'd like to suggest.  Get started by [[Compiling]]!
 
Please do contact us (via [[IRC]] or [[Mailing_Lists|brlcad-devel mailing list]]) if you have any questions, corrections, comments, or ideas of your own that you'd like to suggest.  Get started by [[Compiling]]!
 +
 +
----
  
 
= Template =
 
= Template =
Line 20: Line 22:
 
Code:
 
Code:
 
* list any files you know they will need to read/edit
 
* list any files you know they will need to read/edit
 +
 +
----
  
 
= Code =
 
= Code =
Line 25: Line 29:
 
''Tasks related to writing or refactoring code''
 
''Tasks related to writing or refactoring code''
  
== VERY EASY: Implement a primitive centroid function ==
+
== Implement a primitive centroid function ==
  
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.
Line 40: Line 44:
 
* src/librt/primitives/*/*.c
 
* src/librt/primitives/*/*.c
  
Requirements:
+
== Implement a primitive surface area function ==
* Basic familiarity with C
 
* Basic familiarity with a text editor
 
* Ability to compile BRL-CAD successfully
 
 
 
== VERY EASY: Implement a primitive surface area function ==
 
  
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.
Line 60: Line 59:
 
* src/librt/primitives/*/*.c
 
* src/librt/primitives/*/*.c
  
Requirements:
+
== Move LIBBN comments from source to header files ==
* Basic familiarity with C
 
* Basic familiarity with a text editor
 
* Ability to compile BRL-CAD successfully
 
 
 
== VERY EASY: Move LIBBN comments from source to header files ==
 
  
 
BRL-CAD uses Doxygen source code comments to document the API.  The comments need to be moved from .c source code files to the corresponding .h API header file.  There are approximately 300 public API functions across 30 files in LIBBN.
 
BRL-CAD uses Doxygen source code comments to document the API.  The comments need to be moved from .c source code files to the corresponding .h API header file.  There are approximately 300 public API functions across 30 files in LIBBN.
Line 77: Line 71:
 
* src/libbn/*.c
 
* src/libbn/*.c
  
Requirements:
+
== Implement a primitive volume function ==
* Rudimentary familiarity with C
 
* Basic familiarity with a text editor (copy-paste)
 
 
 
== EASY: Implement a primitive volume function ==
 
  
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.
Line 96: Line 86:
 
* src/librt/primitives/*/*.c
 
* src/librt/primitives/*/*.c
  
Requirements:
+
== Convert BU_SETJUMP/BU_UNSETJUMP blocks into try/catch layout ==
* Basic familiarity with C
 
* Basic familiarity with a text editor
 
* Ability to compile BRL-CAD successfully
 
 
 
== EASY: Convert BU_SETJUMP/BU_UNSETJUMP blocks into try/catch layout ==
 
  
 
BRL-CAD's basic utility library (LIBBU) provides a set of macros, BU_SETJUMP and BU_UNSETJUMP, that are used for exception handling.
 
BRL-CAD's basic utility library (LIBBU) provides a set of macros, BU_SETJUMP and BU_UNSETJUMP, that are used for exception handling.
Line 113: Line 98:
 
* src/**/*.c  
 
* src/**/*.c  
  
Requirements:
+
== Move LIBRT comments from source to header files ==
* Basic familiarity with C
 
* Basic familiarity with a text editor
 
* Ability to compile BRL-CAD successfully
 
 
 
== EASY: Move LIBRT comments from source to header files ==
 
  
 
BRL-CAD uses Doxygen source code comments to document the API.  The comments need to be moved from .c source code files to the corresponding .h API header file.  There are approximately 1000 public API functions across 200 files in LIBRT.
 
BRL-CAD uses Doxygen source code comments to document the API.  The comments need to be moved from .c source code files to the corresponding .h API header file.  There are approximately 1000 public API functions across 200 files in LIBRT.
Line 136: Line 116:
 
* src/librt/primitives/**/*.c
 
* src/librt/primitives/**/*.c
  
Requirements:
+
== Fix 'analyze' command output formatting ==
* Rudimentary familiarity with C
 
* Basic familiarity with a text editor (copy-paste)
 
 
 
== EASY: Fix 'analyze' command output formatting ==
 
  
 
BRL-CAD has an interactive geometry editor called MGED.  MGED has several hundred commands including an "analyze" command that reports basic statistics such as bounding box size for a given geometry object.  Over time, the output format of the analyze command has become misaligned and disorganized with messy printing.
 
BRL-CAD has an interactive geometry editor called MGED.  MGED has several hundred commands including an "analyze" command that reports basic statistics such as bounding box size for a given geometry object.  Over time, the output format of the analyze command has become misaligned and disorganized with messy printing.
Line 151: Line 127:
 
* src/libged/analyze.c
 
* src/libged/analyze.c
  
Requirements:
+
== Camera 360: A script to capture images while rotating the view around a scene ==
* Familiarity with C
 
* Ability to compile and run MGED
 
 
 
== EASY: Camera 360: A script to capture images while rotating the view around a scene ==
 
  
 
BRL-CAD allows the viewing angle for a scene to be set through a number of parameters. These are the azimuth, elevation, twist and also the amount of zoom for the scene. To render a scene a user first sets the view in MGED and then saves the view parameters in a BASH script. This script contains a call to the BRL-CAD ray tracing tool '''rt'''. The appropriate settings to its command line flags are written such that the images are rendered from the view set by the user in MGED.  
 
BRL-CAD allows the viewing angle for a scene to be set through a number of parameters. These are the azimuth, elevation, twist and also the amount of zoom for the scene. To render a scene a user first sets the view in MGED and then saves the view parameters in a BASH script. This script contains a call to the BRL-CAD ray tracing tool '''rt'''. The appropriate settings to its command line flags are written such that the images are rendered from the view set by the user in MGED.  
Line 170: Line 142:
 
* src/**/*.c
 
* src/**/*.c
  
Requirements:
+
== Close MGED when both its windows are closed ==
* Familiarity with C and BASH scripting
 
* Ability to compile and run MGED
 
 
 
== EASY: Close MGED when both its windows are closed ==
 
  
 
BRL-CAD has an interactive geometry editor called MGED. It's often the starting point for beginners and allows creation and manipulation of models using commands. When MGED is invoked, then it creates 2 windows :  
 
BRL-CAD has an interactive geometry editor called MGED. It's often the starting point for beginners and allows creation and manipulation of models using commands. When MGED is invoked, then it creates 2 windows :  
Line 189: Line 157:
 
* src/mged/mged.c
 
* src/mged/mged.c
  
Requirements:
+
== Implement parallel support for Windows ==
* Familiarity with C
 
* Ability to compile and run MGED
 
 
 
== EASY: Implement parallel support for Windows ==
 
  
 
BRL-CAD works pervasively on symmetric multiprocessing (SMP) systems, i.e. computers with multiple CPUs or cores.  However, support for SMP is implemented for each distinct platform.  BRL-CAD runs on Windows, but presently only in a single-threaded mode.
 
BRL-CAD works pervasively on symmetric multiprocessing (SMP) systems, i.e. computers with multiple CPUs or cores.  However, support for SMP is implemented for each distinct platform.  BRL-CAD runs on Windows, but presently only in a single-threaded mode.
Line 205: Line 169:
 
* src/libbu/semaphore.c
 
* src/libbu/semaphore.c
  
Requirements:
+
== Decouple LIBDM from LIBGED ==
* Familiarity with C source code
 
* Familiarity with compiling on Windows
 
 
 
== MEDIUM: Decouple LIBDM from LIBGED ==
 
  
 
BRL-CAD has a 3D display manager library (LIBDM) and a geometry editor command library (LIBGED).  For clean encapsulation and library management, it's desirable to keep library dependencies to a minimum.  LIBGED presently makes direct calls to LIBDM for a "screengrab" command.  Properly fixed, it should be possible to remove the LIBDM linkage from LIBGED's build file and the command still work as expected.
 
BRL-CAD has a 3D display manager library (LIBDM) and a geometry editor command library (LIBGED).  For clean encapsulation and library management, it's desirable to keep library dependencies to a minimum.  LIBGED presently makes direct calls to LIBDM for a "screengrab" command.  Properly fixed, it should be possible to remove the LIBDM linkage from LIBGED's build file and the command still work as expected.
Line 223: Line 183:
 
* src/libged/CMakeLists.txt
 
* src/libged/CMakeLists.txt
  
Requirements:
+
== Separate out LIBNMG from LIBRT ==
* Familiarity with C source code
 
* Familiarity with C function callbacks
 
 
 
== MEDIUM: Separate out LIBNMG from LIBRT ==
 
  
 
BRL-CAD has an N-Manifold Geometry (NMG) library embedded within our ray tracing (RT) library.  The NMG source code is already isolated and separate but not cleanly and not into its own library.
 
BRL-CAD has an N-Manifold Geometry (NMG) library embedded within our ray tracing (RT) library.  The NMG source code is already isolated and separate but not cleanly and not into its own library.
Line 241: Line 197:
 
* src/librt/primitives/nmg
 
* src/librt/primitives/nmg
  
Requirements:
+
== implement runtime detection of SSE ==
* Familiarity with C source code
 
* Basic familiarity with autoconf/automake/libtool build system
 
 
 
== HARD: implement runtime detection of SSE ==
 
  
 
BRL-CAD will optionally leverage SSE instructions for some operations but SSE-support is set at compile-time.  If you attempt to perform SSE instructions on non-SSE hardware, it'll basically halt the application with an illegal instruction exception.   
 
BRL-CAD will optionally leverage SSE instructions for some operations but SSE-support is set at compile-time.  If you attempt to perform SSE instructions on non-SSE hardware, it'll basically halt the application with an illegal instruction exception.   
Line 257: Line 209:
 
* src/libbu
 
* src/libbu
  
Requirements:
+
== Integrate hi/lo geometry wireframe modifications==
* Familiarity with C source code
 
* Access to non-SSE hardware or hardware where SSE can be disabled (for testing)
 
 
 
== HARD: Integrate hi/lo geometry wireframe modifications==
 
  
 
BRL-CAD presently draws wireframes of geometry with a fixed level of detail.  A contributor implemented support for "high" and "low" detail wireframes but their changes were to a very old version that could not be simply applied to the current source code.
 
BRL-CAD presently draws wireframes of geometry with a fixed level of detail.  A contributor implemented support for "high" and "low" detail wireframes but their changes were to a very old version that could not be simply applied to the current source code.
Line 273: Line 221:
 
* src/librt/primitives/**/*.c  (the *_tess() functions)
 
* src/librt/primitives/**/*.c  (the *_tess() functions)
  
Requirements:
+
== Fix Bounding Box function for BoT primitive ==
* Familiarity reading and writing C source code
 
* Basic familiarity with BRL-CAD's MGED
 
 
 
== HARD: Fix Bounding Box function for BoT primitive ==
 
  
 
BRL-CAD provides functions for its geometric primitives that define a bounding box - a box that completely encloses the volume described by the primitive.  Ideally, these boxes are as small as possible while still enclosing the primitive.  Currently the routine for BoTs is incorrect.
 
BRL-CAD provides functions for its geometric primitives that define a bounding box - a box that completely encloses the volume described by the primitive.  Ideally, these boxes are as small as possible while still enclosing the primitive.  Currently the routine for BoTs is incorrect.
Line 288: Line 232:
 
* src/librt/primitives/bot/bot.c  (the rt_bot_bbox function)
 
* src/librt/primitives/bot/bot.c  (the rt_bot_bbox function)
  
Requirements:
+
== Implement a primitive UV-mapping callback ==
* Familiarity reading and writing C source code
 
* Basic familiarity with BRL-CAD's MGED
 
  
== HARD: Implement a primitive UV-mapping callback ==
+
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  One of those functions describes a UV mapping of the object's surface, which is used for things like texture and bump mapping.  An example of this is rt_ell_uv() in¬†the src/librt/primitives/ell/ell.c source file for an ellipsoid.  Several of our more complex primitive types (such as BoT, NMG, and BREP/NURBS) do not presently implement a UV-mapping function leading to unexpected runtime behavior.
 
 
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones.  Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid.  One of those functions describes a UV mapping of the object's surface, which is used for things like texture and bump mapping.  An example of this is rt_ell_uv() in the src/librt/primitives/ell/ell.c source file for an ellipsoid.  Several of our more complex primitive types (such as BoT, NMG, and BREP/NURBS) do not presently implement a UV-mapping function leading to unexpected runtime behavior.
 
  
 
This task involves implementing a UV-mapping callback for any of the primitives that do not already have a functional UV-callback defined.
 
This task involves implementing a UV-mapping callback for any of the primitives that do not already have a functional UV-callback defined.
Line 307: Line 247:
 
References:
 
References:
 
* http://en.wikipedia.org/wiki/UV_mapping
 
* http://en.wikipedia.org/wiki/UV_mapping
 
Requirements:
 
* Familiarity writing C source code
 
* Basic familiarity with UV-mapping
 
  
 
----
 
----
 
 
=Documentation=
 
=Documentation=
 
----
 
----
 
''Tasks related to creating/editing documents''
 
''Tasks related to creating/editing documents''
  
== EASY: Add missing documentation (for JUST ONE command) ==
+
== Add missing documentation (for JUST ONE command) ==
  
 
BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:
 
BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:
Line 332: Line 267:
 
* doc/docbook/system/man1/en/*.xml
 
* doc/docbook/system/man1/en/*.xml
  
Requirements:
+
== Write "MGED Interface" reference document==
* Basic familiarity with using a text editor
 
* Basic familiarity writing in a tagged format (Docbook format is ''very'' similar to html) -- many examples provided
 
* Ability to figure out how to use the command you're documenting (most are very simple)
 
 
 
== EASY: Write "MGED Interface" reference document==
 
  
 
BRL-CAD's primary geometry editor is called MGED.  MGED's documentation is extensive but incomplete without a concise 1 or 2 page document that details MGED's interface.  
 
BRL-CAD's primary geometry editor is called MGED.  MGED's documentation is extensive but incomplete without a concise 1 or 2 page document that details MGED's interface.  
Line 351: Line 281:
 
* http://www.audioease.com/Pages/Altiverb/features/2small.jpg
 
* http://www.audioease.com/Pages/Altiverb/features/2small.jpg
  
Requirements:
+
== Convert src/conv man pages to valid Docbook  ==
* Familiarity with word processing software
 
* Basic familiarity with MGED
 
 
 
== MEDIUM: Convert src/conv man pages to valid Docbook  ==
 
  
 
BRL-CAD is in the process of converting its documentation into Docbook 4.5 format, in order to enable automatic generation of output in different formats (html, pdf, man) from a single source.  This conversion includes existing UNIX man pages.
 
BRL-CAD is in the process of converting its documentation into Docbook 4.5 format, in order to enable automatic generation of output in different formats (html, pdf, man) from a single source.  This conversion includes existing UNIX man pages.
Line 370: Line 296:
 
* nxml Emacs mode: http://www.thaiopensource.com/nxml-mode/
 
* nxml Emacs mode: http://www.thaiopensource.com/nxml-mode/
  
Requirements:
+
== Write a "BRL-CAD Commands Quick Reference" document ==
* Basic ability to understand and work with xml files
 
* Computer environment that can build BRL-CAD docs (xsltproc, autotools) and ability to set up BRL-CAD for building.
 
 
 
== MEDIUM: Write a "BRL-CAD Commands Quick Reference" document ==
 
  
 
There is already a command quick reference for BRL-CAD's MGED geometry editing tool, but there is not a similar document for BRL-CAD's 400+ command-line commands.
 
There is already a command quick reference for BRL-CAD's MGED geometry editing tool, but there is not a similar document for BRL-CAD's 400+ command-line commands.
Line 386: Line 308:
 
* http://brlcad.org/w/images/5/52/MGED_Quick_Reference_Card.pdf
 
* http://brlcad.org/w/images/5/52/MGED_Quick_Reference_Card.pdf
  
Requirements:
+
== Write a "Technical Overview of BRL-CAD" document ==
* Familiarity with layout software
 
* Basic familiarity with BRL-CAD
 
 
 
== HARD: Write a "Technical Overview of BRL-CAD" document ==
 
  
 
This task involves describing everything in BRL-CAD succinctly yet comprehensively.  Survey of all the major features, methodologies, and tools implemented in BRL-CAD with coverage on code maturity, library encapsulation, and tool aggregation.  The document should be less than 10 pages, possibly only 1 or 2 pages, but cover multiple layers of information concisely.
 
This task involves describing everything in BRL-CAD succinctly yet comprehensively.  Survey of all the major features, methodologies, and tools implemented in BRL-CAD with coverage on code maturity, library encapsulation, and tool aggregation.  The document should be less than 10 pages, possibly only 1 or 2 pages, but cover multiple layers of information concisely.
Line 400: Line 318:
 
* http://brlcad.org/wiki/Overview
 
* http://brlcad.org/wiki/Overview
  
Requirements:
+
== Add missing documentation (for ALL missing) ==
* In-depth familiarity with BRL-CAD
 
 
 
 
 
== HARD: Add missing documentation (for ALL missing) ==
 
  
 
BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:
 
BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:
Line 417: Line 331:
 
* doc/docbook/system/man1/en/Makefile.am
 
* doc/docbook/system/man1/en/Makefile.am
 
* doc/docbook/system/man1/en/*.xml
 
* doc/docbook/system/man1/en/*.xml
 
Requirements:
 
* Basic familiarity with using a text editor
 
* Basic familiarity writing in a tagged format (Docbook format is ''very'' similar to html) -- many examples provided
 
  
 
----
 
----
  
=Outreach=
+
= Outreach =
 
----
 
----
 
''Tasks related to community management and outreach/marketing''
 
''Tasks related to community management and outreach/marketing''
  
== EASY: Write solicitation for new website designer ==
+
== Write solicitation for new website designer ==
  
 
The BRL-CAD website is in need of a design overhaul.
 
The BRL-CAD website is in need of a design overhaul.
Line 439: Line 349:
 
* http://brlcad.org
 
* http://brlcad.org
  
Requirements:
+
== Model new BRL-CAD Logo using BRL-CAD ==
* Ability to write well, clearly, and convincingly
 
* Basic familiarity with the BRL-CAD website
 
 
 
== EASY: Model new BRL-CAD Logo using BRL-CAD ==
 
  
 
The winner of the recent BRL-CAD Logo contest is a clean depiction of two interlocked components. Modeling the new Logo in BRL-CAD without using NURBS would require some careful arrangement, but would provide an attractive three dimensional rendering.
 
The winner of the recent BRL-CAD Logo contest is a clean depiction of two interlocked components. Modeling the new Logo in BRL-CAD without using NURBS would require some careful arrangement, but would provide an attractive three dimensional rendering.
Line 456: Line 362:
 
* Introduction to MGED at http://brlcad.org/wiki/Documentation
 
* Introduction to MGED at http://brlcad.org/wiki/Documentation
  
== EASY: Write BRL-CAD News article on .deb/.rpm builds ==
+
== Write BRL-CAD News article on .deb/.rpm builds ==
  
 
BRL-CAD has a new maintainer, Jordi Sayol, for managing .deb and .rpm builds.  Interview the developer, obtain details on how the releases are produced, what platforms are supported, etc, and write up an article for our Community Publication Portal (CPP)
 
BRL-CAD has a new maintainer, Jordi Sayol, for managing .deb and .rpm builds.  Interview the developer, obtain details on how the releases are produced, what platforms are supported, etc, and write up an article for our Community Publication Portal (CPP)
Line 467: Line 373:
 
* http://brlcad.org/wiki/Community_Publication_Portal
 
* http://brlcad.org/wiki/Community_Publication_Portal
  
Requirements:
+
== Write a BRL-CAD model showcase article ==
* Decent writing and/or journalistic skills
 
 
 
== MEDIUM: Write a BRL-CAD model showcase article ==
 
  
 
BRL-CAD has several geometry models developed by community members that showcase the power and applicability of BRL-CAD to various domains.  For this task, you'd be expected to interview one or more individuals to obtain information and pictures about their project, write up a descriptive overview of their model, the goals of the project, and any interesting ancillary information that may be relevant.  There are presently several candidate topics listed in our Community Publication Portal (CPP).
 
BRL-CAD has several geometry models developed by community members that showcase the power and applicability of BRL-CAD to various domains.  For this task, you'd be expected to interview one or more individuals to obtain information and pictures about their project, write up a descriptive overview of their model, the goals of the project, and any interesting ancillary information that may be relevant.  There are presently several candidate topics listed in our Community Publication Portal (CPP).
Line 481: Line 384:
 
* http://brlcad.org/wiki/Community_Publication_Portal
 
* http://brlcad.org/wiki/Community_Publication_Portal
  
Requirements:
+
== Design a "Commercial CAD Comparison" diagram ==
* Decent writing and/or journalistic skills
 
* Ability to investigate and aggregate information from a variety of sources
 
 
 
== MEDIUM: Design a "Commercial CAD Comparison" diagram ==
 
  
 
New users frequently ask how BRL-CAD compares to other major commercial CAD systems such as CATIA, Unigraphics/NX, Pro/ENGINEER, Solidworks, and AutoCAD.  BRL-CAD has many of the same features and it would be very useful to visualize the feature overlap graphically with a diagram.
 
New users frequently ask how BRL-CAD compares to other major commercial CAD systems such as CATIA, Unigraphics/NX, Pro/ENGINEER, Solidworks, and AutoCAD.  BRL-CAD has many of the same features and it would be very useful to visualize the feature overlap graphically with a diagram.
Line 497: Line 396:
 
* Example feature comparisons (although not a diagram): http://en.wikipedia.org/wiki/Comparison_of_3D_computer_graphics_software
 
* Example feature comparisons (although not a diagram): http://en.wikipedia.org/wiki/Comparison_of_3D_computer_graphics_software
 
* Additional feature comparisons (also not a diagram): http://en.wikipedia.org/wiki/Comparison_of_CAD_editors_for_CAE
 
* Additional feature comparisons (also not a diagram): http://en.wikipedia.org/wiki/Comparison_of_CAD_editors_for_CAE
 
Requirements:
 
* Basic familiarity with multiple commercial CAD software packages
 
* Basic familiarity with BRL-CAD
 
  
 
----
 
----
  
=Quality Assurance=
+
= Quality Assurance =
 
----
 
----
 
''Tasks related to testing and ensuring code is of high quality''
 
''Tasks related to testing and ensuring code is of high quality''
  
== EASY: Develop an N-Manifold Geometry (NMG) testing framework==
+
== Develop an N-Manifold Geometry (NMG) testing framework==
  
 
BRL-CAD implements polygonal facetted geometry as "NMG" geometry, which is then used for converting from an implicit constructive solid geometry (CSG) representation to a mesh format.  This is a huge portion of BRL-CAD's core libraries that is used by dozens of tools and commands so there is a need for improved robustness.
 
BRL-CAD implements polygonal facetted geometry as "NMG" geometry, which is then used for converting from an implicit constructive solid geometry (CSG) representation to a mesh format.  This is a huge portion of BRL-CAD's core libraries that is used by dozens of tools and commands so there is a need for improved robustness.
Line 525: Line 420:
 
* http://code.google.com/p/googletest/
 
* http://code.google.com/p/googletest/
  
Requirements:
+
== Create comprehensive utility library (LIBBU) API unit tests ==
* Basic familiarity with scripting or a testing framework
 
 
 
== MEDIUM: Create comprehensive utility library (LIBBU) API unit tests ==
 
  
 
There are more than 300 library functions in our core LIBBU library.  As a core library used by nearly every one of BRL-CAD's tools, testing those functions for correct behavior is important.
 
There are more than 300 library functions in our core LIBBU library.  As a core library used by nearly every one of BRL-CAD's tools, testing those functions for correct behavior is important.
Line 543: Line 435:
 
Time: <3 days
 
Time: <3 days
  
Requirements:
+
== Create comprehensive numerics library (LIBBN) API unit tests ==
* Basic familiarity with C
 
* Familiarity with scripting or a testing framework
 
 
 
== MEDIUM: Create comprehensive numerics library (LIBBN) API unit tests ==
 
  
 
There are more than 300 library functions in our core LIBBN library.  As a core library used by nearly every one of BRL-CAD's tools, testing those functions for correct behavior is important.
 
There are more than 300 library functions in our core LIBBN library.  As a core library used by nearly every one of BRL-CAD's tools, testing those functions for correct behavior is important.
Line 564: Line 452:
 
* http://code.google.com/p/googletest/
 
* http://code.google.com/p/googletest/
  
Requirements:
+
== Create a comprehensive unit test for bn_dist_pt3_pt3() ==
* Basic familiarity with C
 
* Familiarity with scripting or a testing framework
 
 
 
== MEDIUM: Create a comprehensive unit test for bn_dist_pt3_pt3() ==
 
  
 
There are more than 300 library functions in our LIBBN numerics library.  Creating a comprehensive unit test involves exhaustively exploring all possible inputs to the function, testing them for proper behavior, and characterizing the output in a PASS/FAIL fashion.
 
There are more than 300 library functions in our LIBBN numerics library.  Creating a comprehensive unit test involves exhaustively exploring all possible inputs to the function, testing them for proper behavior, and characterizing the output in a PASS/FAIL fashion.
Line 583: Line 467:
 
* http://code.google.com/p/googletest/
 
* http://code.google.com/p/googletest/
  
Requirements:
+
== Find, reproduce, confirm, and report any bug in Archer ==
* Basic familiarity with unit testing
 
* Strong critical thinking skills
 
* Basic familiarity with C
 
* Familiarity with scripting or a testing framework
 
 
 
== EASY: Find, reproduce, confirm, and report any bug in Archer ==
 
  
 
Archer is our new modeling interface and a soon-to-be replacement for our long-standing MGED geometry editor.  It undoubtedly has bugs.  It's your job to find them, but do so in a manner that is so obvious that one of the other devs will be able to instantly reproduce the bug given your instructions.  Crashing bugs are best, but may require learning how to use the tool with minimal documentation.
 
Archer is our new modeling interface and a soon-to-be replacement for our long-standing MGED geometry editor.  It undoubtedly has bugs.  It's your job to find them, but do so in a manner that is so obvious that one of the other devs will be able to instantly reproduce the bug given your instructions.  Crashing bugs are best, but may require learning how to use the tool with minimal documentation.
Line 603: Line 481:
 
----
 
----
  
=Research=
+
= Research =
 
----
 
----
 
''Tasks related to studying a problem and recommending solutions''
 
''Tasks related to studying a problem and recommending solutions''
  
== EASY: Investigate performance of setting thread affinity ==
+
== Investigate performance of setting thread affinity ==
  
 
BRL-CAD's raytrace library (LIBRT) is pervasively multithreaded using routines defined in our basic utility library (LIBBU) for detecting an using multiple CPUs/cores/threads.
 
BRL-CAD's raytrace library (LIBRT) is pervasively multithreaded using routines defined in our basic utility library (LIBBU) for detecting an using multiple CPUs/cores/threads.
Line 619: Line 497:
 
* src/libbu/semaphore.c
 
* src/libbu/semaphore.c
  
Requirements:
+
== Determine why solids.sh fails on 64-bit ==
* Basic familiarity with C code
 
* Ability to compile and run BRL-CAD
 
 
 
== MEDIUM: Determine why solids.sh fails on 64-bit ==
 
  
 
BRL-CAD has a regression test script called solids.sh that creates a bunch of primitives, renders an image of those primitives, and then compares that image to a reference image.  On (most?) 64-bit platforms, the test is off by several RGB values for exactly 3 pixels.
 
BRL-CAD has a regression test script called solids.sh that creates a bunch of primitives, renders an image of those primitives, and then compares that image to a reference image.  On (most?) 64-bit platforms, the test is off by several RGB values for exactly 3 pixels.
Line 634: Line 508:
 
* regress/solids.sh
 
* regress/solids.sh
  
Requirements:
+
== Investigate permuted vertex lists from g-iges + iges-g ==
* Familiarity compiling and debugging C code
 
* Access to a 64-bit platform
 
 
 
== MEDIUM: Investigate permuted vertex lists from g-iges + iges-g ==
 
  
 
BRL-CAD has a geometry exporter and importer for the International Graphics Exchange Standard (IGES) file format.  If you run our g-iges exporter on some geometry, then run iges-g on that same geometry to import it back to BRL-CAD format, the geometry will have permuted vertex lists.  Particularly for geometry already in polygonal format, such as our NMG or BoT geometry, this conversion should result in identical geometry but presently does not.
 
BRL-CAD has a geometry exporter and importer for the International Graphics Exchange Standard (IGES) file format.  If you run our g-iges exporter on some geometry, then run iges-g on that same geometry to import it back to BRL-CAD format, the geometry will have permuted vertex lists.  Particularly for geometry already in polygonal format, such as our NMG or BoT geometry, this conversion should result in identical geometry but presently does not.
Line 649: Line 519:
 
* src/conv/iges
 
* src/conv/iges
  
Requirements:
+
== Investigate GMP integration ==
* Familiarity compiling and debugging C code
 
* Ability to compile and run BRL-CAD's g-iges and iges-g converters
 
 
 
== HARD: Investigate GMP integration ==
 
  
 
BRL-CAD uses a fastf_t typedef for most all math operations that is usually a "double" floating point type.  We would like to provide the option for resorting to exact arithmetic if possible by merely redefining fastf_t to a C++ type sufficiently overloaded to behave the same.
 
BRL-CAD uses a fastf_t typedef for most all math operations that is usually a "double" floating point type.  We would like to provide the option for resorting to exact arithmetic if possible by merely redefining fastf_t to a C++ type sufficiently overloaded to behave the same.
Line 668: Line 534:
 
* http://gmplib.org/
 
* http://gmplib.org/
  
Requirements:
+
== Investigate the status of our command spreadsheet ==
* Familiarity with C
 
* Familiarity with GMP
 
* Basic familiarity with (BRL-CAD's) LIBBN
 
 
 
== HARD: Investigate the status of our command spreadsheet ==
 
  
 
We have a spreadsheet filled with information about all of BRL-CAD's 400+ commands including details about what command line options, inputs, and outputs are supported.  The spreadsheet is not complete, however, and hasn't been reviewed in a couple years.
 
We have a spreadsheet filled with information about all of BRL-CAD's 400+ commands including details about what command line options, inputs, and outputs are supported.  The spreadsheet is not complete, however, and hasn't been reviewed in a couple years.
Line 686: Line 547:
 
References:
 
References:
 
* Existing spreadsheet available on request
 
* Existing spreadsheet available on request
 
Requirements:
 
* Basic familiarity with C, ability to recognize getopt() option strings
 
* Familiarity with the UNIX command line
 
* Familiarity with manual pages
 
  
 
----
 
----
  
=Training=
+
= Training =
 
----
 
----
 
''Tasks related to helping others learn more''
 
''Tasks related to helping others learn more''
  
== VERY EASY: LIBBU Doxygen cleanup ==
+
== LIBBU Doxygen cleanup ==
  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 300 documented API function calls in LIBBU.  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 300 documented API function calls in LIBBU.  
Line 717: Line 573:
 
* http://www.stack.nl/~dimitri/doxygen/
 
* http://www.stack.nl/~dimitri/doxygen/
  
Requirements:
+
== LIBBN Doxygen cleanup ==
* Basic familiarity with Doxygen
 
 
 
== EASY: LIBBN Doxygen cleanup ==
 
  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 300 documented API function calls in LIBBN.  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 300 documented API function calls in LIBBN.  
Line 741: Line 594:
 
* http://www.stack.nl/~dimitri/doxygen/
 
* http://www.stack.nl/~dimitri/doxygen/
  
Requirements:
+
== LIBWDB Doxygen cleanup ==
* Basic familiarity with Doxygen
 
 
 
== EASY: LIBWDB Doxygen cleanup ==
 
  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 100 documented API function calls in LIBWDB.  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 100 documented API function calls in LIBWDB.  
Line 764: Line 614:
 
* http://www.stack.nl/~dimitri/doxygen/
 
* http://www.stack.nl/~dimitri/doxygen/
  
Requirements:
+
== LIBRT Doxygen cleanup ==
* Basic familiarity with Doxygen
 
 
 
== MEDIUM: LIBRT Doxygen cleanup ==
 
  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 1000 documented API function calls in LIBRT.  
 
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.  There are approximately 1000 documented API function calls in LIBRT.  
Line 789: Line 636:
 
* http://www.stack.nl/~dimitri/doxygen/
 
* http://www.stack.nl/~dimitri/doxygen/
  
Requirements:
+
== "Introduction to BRL-CAD Tutorial" ==
* Basic familiarity with Doxygen
 
 
 
== MEDIUM: "Introduction to BRL-CAD Tutorial" ==
 
  
 
BRL-CAD includes an extensive introduction to  MGED tutorial series, but not a succinct introduction to BRL-CAD (the suite).
 
BRL-CAD includes an extensive introduction to  MGED tutorial series, but not a succinct introduction to BRL-CAD (the suite).
Line 800: Line 644:
 
Time: <2 days
 
Time: <2 days
  
Requirements:
+
== Write a "BRL-CAD Ray Tracing Shaders" tutorial ==
* Familiarity with layout software
 
* Basic familiarity with BRL-CAD command line tools
 
* Basic familiarity with UNIX
 
 
 
== MEDIUM: Write a "BRL-CAD Ray Tracing Shaders" tutorial ==
 
  
 
BRL-CAD includes numerous shaders that let you specify different optical effects during ray tracing.
 
BRL-CAD includes numerous shaders that let you specify different optical effects during ray tracing.
Line 820: Line 659:
 
* http://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf
 
* http://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf
  
Requirements:
+
----
* Basic familiarity with BRL-CAD
 
* Basic familiarity with word processing software
 
  
=User Interface=
+
= User Interface =
 
----
 
----
 
''Tasks related to user experience research or user interface design and interaction''
 
''Tasks related to user experience research or user interface design and interaction''
  
== EASY: Design an MGED command spreadsheet ==
+
== Design an MGED command spreadsheet ==
  
 
BRL-CAD's primary solid geometry modeling application is called MGED.  MGED contains a comprehensive set of more than 700 commands for manipulating, viewing, and inspecting geometry.  There is a need to more effectively manage those commands, characterize them all, and get a "big picture" of the command landscape so that usability may be addressed.
 
BRL-CAD's primary solid geometry modeling application is called MGED.  MGED contains a comprehensive set of more than 700 commands for manipulating, viewing, and inspecting geometry.  There is a need to more effectively manage those commands, characterize them all, and get a "big picture" of the command landscape so that usability may be addressed.
Line 839: Line 676:
 
* An existing spreadsheet already being used for BRL-CAD (i.e., non-MGED) commands is available.
 
* An existing spreadsheet already being used for BRL-CAD (i.e., non-MGED) commands is available.
  
Requirements:
+
== Create prototype 2D CAD drawing(s) ==
* Basic ability to use spreadsheet software
 
* Ability to characterize information in a useful tabular form
 
 
 
== EASY: Create prototype 2D CAD drawing(s) ==
 
  
 
BRL-CAD provides limited services for drafting features including the production of 2D CAD drawings (blueprints).
 
BRL-CAD provides limited services for drafting features including the production of 2D CAD drawings (blueprints).
Line 858: Line 691:
 
* http://www.ptc.com/WCMS/files/45691/en/4307_FoundationXE_DS.pdf
 
* http://www.ptc.com/WCMS/files/45691/en/4307_FoundationXE_DS.pdf
 
   
 
   
Requirements:
+
== Create prototype CAD GUI layout diagram ==
* Familiarity with CAD drawings
 
* Ability to recognize important features in CAD drawings
 
* Familiarity with layout/diagram software
 
 
 
== MEDIUM: Create prototype CAD GUI layout diagram ==
 
  
 
BRL-CAD's usability is notoriously complex and "expert friendly".  MGED and Archer are the main geometry editors, with drastically different user interfaces.
 
BRL-CAD's usability is notoriously complex and "expert friendly".  MGED and Archer are the main geometry editors, with drastically different user interfaces.
Line 874: Line 702:
 
* http://brlcad.org/design/gui
 
* http://brlcad.org/design/gui
  
Requirements:
+
== Reorganize MGED menu ==  
* Basic familiarity with BRL-CAD's MGED and Archer tools
 
* Basic familiarity with software usability metrics
 
* Familiarity creating a layout prototype
 
 
 
== MEDIUM: Reorganize MGED menu ==  
 
  
 
BRL-CAD's main graphical user interface, MGED, is heavily menu-driven but not exceptionally well organized.  This task involves performing an exhaustive review of MGED's various menus, including temporary menus when in a given editing state, reorganizing them for logical groupings, and rewording them for clarity.  It's necessary to learn the basics of the MGED interface in order to understand what the various options do.
 
BRL-CAD's main graphical user interface, MGED, is heavily menu-driven but not exceptionally well organized.  This task involves performing an exhaustive review of MGED's various menus, including temporary menus when in a given editing state, reorganizing them for logical groupings, and rewording them for clarity.  It's necessary to learn the basics of the MGED interface in order to understand what the various options do.
Line 890: Line 713:
 
* Introduction to MGED at http://brlcad.org/wiki/Documentation
 
* Introduction to MGED at http://brlcad.org/wiki/Documentation
  
Requirements:
+
== Categorize all of BRL-CAD's commands into a spreadsheet ==
* Basic ability to learn a GUI
 
* Basic understanding of usability concepts and ability to organize items logically
 
 
 
== HARD: Categorize all of BRL-CAD's commands into a spreadsheet ==
 
  
 
BRL-CAD is a suite of more than 400 processing tools, image tools, geometry converters, and more.  There is an existing spreadsheet that characterizes all of the available commands in terms of inputs, outputs, and options, but there is insufficient characterization of BRL-CAD's commands as to how they logically group and work together.
 
BRL-CAD is a suite of more than 400 processing tools, image tools, geometry converters, and more.  There is an existing spreadsheet that characterizes all of the available commands in terms of inputs, outputs, and options, but there is insufficient characterization of BRL-CAD's commands as to how they logically group and work together.
Line 904: Line 723:
 
References:
 
References:
 
* A spreadsheet template will be provided.
 
* A spreadsheet template will be provided.
 
Requirements:
 
* Basic ability to use spreadsheet software
 
* Ability to quickly browse files for information
 
* Ability to be methodical and obsessive
 

Revision as of 17:40, 5 November 2012

This is a list of really quick projects that are expected to take less than two hours to complete. It's a great starting point for any new contributor that would like to work on BRL-CAD. These tasks are all roughly the same complexity for an average person to complete (whatever that means) with very minimal familiarity expected.

Any requirements are listed along with any background information helpful for completing the task.

Please do contact us (via IRC or brlcad-devel mailing list) if you have any questions, corrections, comments, or ideas of your own that you'd like to suggest. Get started by Compiling!


Contents

Template


This is the template to be used for all tasks:

Template example title

Brief background information not specific to the task goes first. It might help to write this paragraph second. Keep it succinct.

This task involves ... the rest goes here. Remember, less than two hours expected for average or random contributor to do the work after reading this description. The resulting task should be directly measurable without subjective interpretation. Tell them exactly what they need to do. Be specific.

References:

  • optionally list any url's that provide relevant background information

Code:

  • list any files you know they will need to read/edit

Code


Tasks related to writing or refactoring code

Implement a primitive centroid function

BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones. Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid. Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.

This task involves writing a new callback function that takes an rt_db_internal object and calculates its centroid (as a point_t 3D point). Any of the primitives that do not already have a centroid callback are fair game.

Time: <1 day

References:

Code:

  • src/librt/primitives/*/*.c

Implement a primitive surface area function

BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones. Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid. Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.

This task involves writing a new callback function that takes an rt_db_internal object and calculates the surface area (units are mm^2). Any of the primitives that do not already have a surface area callback are fair game.

Time: <1 day

References:

Code:

  • src/librt/primitives/*/*.c

Move LIBBN comments from source to header files

BRL-CAD uses Doxygen source code comments to document the API. The comments need to be moved from .c source code files to the corresponding .h API header file. There are approximately 300 public API functions across 30 files in LIBBN.

This task involves editing source code to move comments, cleaning up comment formatting, and verifying Doxygen output.

Time: <1 day

Code:

  • include/bn.h
  • src/libbn/*.c

Implement a primitive volume function

BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones. Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid. Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives.

This task involves writing a new callback function that takes an rt_db_internal object and calculates the volume (units are mm^3). Any of the primitives that do not already have a volume callback are fair game.

Time: <1 days

References:

Code:

  • src/librt/primitives/*/*.c

Convert BU_SETJUMP/BU_UNSETJUMP blocks into try/catch layout

BRL-CAD's basic utility library (LIBBU) provides a set of macros, BU_SETJUMP and BU_UNSETJUMP, that are used for exception handling.

This task involves restructuring the logic where those macros are used so that they are all consistently in a more familiar "try/catch" ordering. Most are merely in "catch/try" order and need to be reversed, some are in an unstructured layout. There are approximately 50 places that need to be updated.

Time: < 2 days

Code:

  • include/bu.h
  • src/**/*.c

Move LIBRT comments from source to header files

BRL-CAD uses Doxygen source code comments to document the API. The comments need to be moved from .c source code files to the corresponding .h API header file. There are approximately 1000 public API functions across 200 files in LIBRT.

This task involves editing source code to move comments, cleaning up comment formatting, and verifying Doxygen output.

Time: <4 days

Code:

  • include/raytrace.h
  • include/nmg.h
  • include/db.h
  • include/db5.h
  • src/librt/*.c
  • src/librt/comb/*.c
  • src/librt/binunif/*.c
  • src/librt/primitives/**/*.c

Fix 'analyze' command output formatting

BRL-CAD has an interactive geometry editor called MGED. MGED has several hundred commands including an "analyze" command that reports basic statistics such as bounding box size for a given geometry object. Over time, the output format of the analyze command has become misaligned and disorganized with messy printing.

This task involves cleaning up the basic printf-style printing so that columns line up neatly and the ornamental ascii table lines are properly aligned. The table lines should be rewritten to automatically expand as needed for the content being printed so it doesn't become a repeat maintenance burden in the future.

Time: <2 days

Code:

  • src/libged/analyze.c

Camera 360: A script to capture images while rotating the view around a scene

BRL-CAD allows the viewing angle for a scene to be set through a number of parameters. These are the azimuth, elevation, twist and also the amount of zoom for the scene. To render a scene a user first sets the view in MGED and then saves the view parameters in a BASH script. This script contains a call to the BRL-CAD ray tracing tool rt. The appropriate settings to its command line flags are written such that the images are rendered from the view set by the user in MGED.

The command for invoking rt may be called multiple times in a loop, each time carrying out a small change in the scene such as translating some geometry to achieve basic animation.

This task involves developing a bash script that changes the parameters to rt in every loop iteration such that the view camera revolves around the origin of the scene at a particular distance from it , in the XY plane. The camera should change the view in small increments such that the images are captured in small angular increments. This would allow a video to be created with the effect of walking around a model while inspecting it from all sides.

Note: that an equivalent effect could also be achieved by keeping the view steady but revolving the model gradually by 360 degrees instead.

Time: ~ 3 days

Code:

  • src/**/*.c

Close MGED when both its windows are closed

BRL-CAD has an interactive geometry editor called MGED. It's often the starting point for beginners and allows creation and manipulation of models using commands. When MGED is invoked, then it creates 2 windows :

  • A command window
  • An OpenGL graphics window.

A user types command in the command window and views the results in the graphics window. However when the application is closed then it has a non-intuitive behavior in the sense that even if both the windows are manually closed, the MGED process is not terminated. Thus the proper way of closing it is through the exit command in the MGED command window.

This task involves fixing this behavior such that closing both the windows terminates the process properly.

Time: ~ 4 days

Code:

  • src/mged/mged.c

Implement parallel support for Windows

BRL-CAD works pervasively on symmetric multiprocessing (SMP) systems, i.e. computers with multiple CPUs or cores. However, support for SMP is implemented for each distinct platform. BRL-CAD runs on Windows, but presently only in a single-threaded mode.

This task involves implementing the hooks necessary to make BRL-CAD work in parallel on Windows. This can be achieved with relatively minor source code modifications to two files.

Time: <2 days

Code:

  • src/libbu/parallel.c
  • src/libbu/semaphore.c

Decouple LIBDM from LIBGED

BRL-CAD has a 3D display manager library (LIBDM) and a geometry editor command library (LIBGED). For clean encapsulation and library management, it's desirable to keep library dependencies to a minimum. LIBGED presently makes direct calls to LIBDM for a "screengrab" command. Properly fixed, it should be possible to remove the LIBDM linkage from LIBGED's build file and the command still work as expected.

This task involves breaking the dependency of LIBGED on LIBDM by making LIBGED not directly call any LIBDM functions. To do this, LIBGED will likely need to introduce a callback mechanism in the "ged" struct so that the screengrab command can capture an image without directly calling a LIBDM function.

Time: <3 days

Code:

  • include/ged.h
  • include/dm.h
  • src/libged/screengrab.h
  • src/libged/CMakeLists.txt

Separate out LIBNMG from LIBRT

BRL-CAD has an N-Manifold Geometry (NMG) library embedded within our ray tracing (RT) library. The NMG source code is already isolated and separate but not cleanly and not into its own library.

This task involves moving the NMG source code into its own library directory and making the appropriate build system modifications so that it compiles the new library cleanly. There may be minor source code refactorings necessary to decouple the NMG code from LIBRT, but nothing major is expected.

Time: <3 days

Code:

  • include/raytrace.h
  • include/nmg.h
  • src/librt
  • src/librt/primitives/nmg

implement runtime detection of SSE

BRL-CAD will optionally leverage SSE instructions for some operations but SSE-support is set at compile-time. If you attempt to perform SSE instructions on non-SSE hardware, it'll basically halt the application with an illegal instruction exception.

This task involves implementing a new libbu function that reports whether SSE support is available at runtime. The most prevalent method for doing this is demonstrated by the Mesa folks where you set up an exception handler for SIGILL and attempt an SSE instruction. That's obviously a non-solution for Windows platforms, but is better than nothing and more useful than a Windows-only solution. Even better if you can handle both.

Time: <2 days

Code:

  • include/bu.h
  • src/libbu

Integrate hi/lo geometry wireframe modifications

BRL-CAD presently draws wireframes of geometry with a fixed level of detail. A contributor implemented support for "high" and "low" detail wireframes but their changes were to a very old version that could not be simply applied to the current source code.

This task involves identifying their source code changes (easy), isolating them (relatively easy), applying them to the current source code (maybe tricky, maybe not), documenting the new feature (trivial), and making sure everything works.

Time: <4 days

Code:

  • modified source tarball will be provided
  • src/librt/primitives/**/*.c (the *_tess() functions)

Fix Bounding Box function for BoT primitive

BRL-CAD provides functions for its geometric primitives that define a bounding box - a box that completely encloses the volume described by the primitive. Ideally, these boxes are as small as possible while still enclosing the primitive. Currently the routine for BoTs is incorrect.

This task involves studying the current code for the function rt_bot_bbox and determining what is causing the current inaccuracies (the bb command is a good way to visualize primitive bounding boxes) and making changes to produce a more optimal bounding box. The raytracing prep code in rt_bot_prep does prepare a better bounding box, so that is one place to check.

Time: <4 days

Code:

  • src/librt/primitives/bot/bot.c (the rt_bot_bbox function)

Implement a primitive UV-mapping callback

BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones. Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid. One of those functions describes a UV mapping of the object's surface, which is used for things like texture and bump mapping. An example of this is rt_ell_uv() in the src/librt/primitives/ell/ell.c source file for an ellipsoid. Several of our more complex primitive types (such as BoT, NMG, and BREP/NURBS) do not presently implement a UV-mapping function leading to unexpected runtime behavior.

This task involves implementing a UV-mapping callback for any of the primitives that do not already have a functional UV-callback defined.

Time: <3 days

Code:

  • src/librt/primitives/*/*.c
  • src/librt/primitives/table.c
  • include/rtgeom.h

References:


Documentation


Tasks related to creating/editing documents

Add missing documentation (for JUST ONE command)

BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:

a-d archer asc2g asc2pix bot-bldxf bottest brep_cube brep_simple brickwall btclsh burst bw-a bw-d bwish c-d chan_add clutter contours d-a damdf dauto dauto2 d-bw dconv ddisp d-f dfft d-i dmod double-asc dpeak dsel dsp_add dstat d-u dwin euclid_format euclid_unformat fbgammamod f-d fence fhor f-i g-adrt g-euclid1 g-jack globe g-off i-a i-d i-f ihist imod istat jack-g kurt lowp molecule nmgmodel nmg-sgp off-g pipe pipetest pix2g pix3filter pixcount pixelswap pixembed pixfields pixfieldsep pixflip-fb pixpaste pix-spm pix-yuv plstat pyramid rawbot remapid rlesortmap rletovcr room rtcell rtexample rtfrac rtrad rtsil rtsrv script-tab sketch solshoot sphflake spltest spm-fb ssampview syn tea tea_nmg testfree texturescale torii ttcp tube txyz-pl u-a u-bw u-d u-f umod ustat vcrtorle vegitation wall wdb_example xbmtorle xyz-pl yuv-pix

This task involves writing a failed document for JUST ONE of those commands in the Docbook format. The command documentation should provide a one-sentence description, a detailed paragraph description, explanation of all available command-line options, and one or more examples on how to use the command.

Time: < 2 days

Code:

  • doc/docbook/system/man1/en/Makefile.am
  • doc/docbook/system/man1/en/*.xml

Write "MGED Interface" reference document

BRL-CAD's primary geometry editor is called MGED. MGED's documentation is extensive but incomplete without a concise 1 or 2 page document that details MGED's interface.

This task involves writing an interface reference document that gives a brief descriptive overview of the key bindings, mouse bindings, and primary GUI elements. The shift grips reference should be incorporated, albeit much more concisely and organized.

Time: <2 days

References:

Convert src/conv man pages to valid Docbook

BRL-CAD is in the process of converting its documentation into Docbook 4.5 format, in order to enable automatic generation of output in different formats (html, pdf, man) from a single source. This conversion includes existing UNIX man pages.

This task involves using the doclifter tool to perform a rough conversion to Docbook of all man pages in the src/conv subdirectory of the BRL-CAD source tree (about 40 files), then performing whatever manual corrections are needed to the autogenerated xml files to make them valid Docbook (some conversions have already been done and can serve as guides). The simplest way to confirm the files are successfully converted is to incorporate them into BRL-CAD's build logic for Docbook man pages and view the output using brlman and an html viewer. It is recommended to use the Emacs editor with the nxml mode in order to more easily identify and fix errors, but this is not a requirement.

Time: <4 days

References:

Write a "BRL-CAD Commands Quick Reference" document

There is already a command quick reference for BRL-CAD's MGED geometry editing tool, but there is not a similar document for BRL-CAD's 400+ command-line commands.

This task involves writing a quick reference document similar to the MGED quick reference but for BRL-CAD commands.

Time: <3 days

References:

Write a "Technical Overview of BRL-CAD" document

This task involves describing everything in BRL-CAD succinctly yet comprehensively. Survey of all the major features, methodologies, and tools implemented in BRL-CAD with coverage on code maturity, library encapsulation, and tool aggregation. The document should be less than 10 pages, possibly only 1 or 2 pages, but cover multiple layers of information concisely.

Time: <4 days

References:

Add missing documentation (for ALL missing)

BRL-CAD is an extensive system with more than 400 commands and more than a million pages of documentation, but there are approximately 120 commands that are entirely undocumented:

a-d archer asc2g asc2pix bot-bldxf bottest brep_cube brep_simple brickwall btclsh burst bw-a bw-d bwish c-d chan_add clutter contours d-a damdf dauto dauto2 d-bw dconv ddisp d-f dfft d-i dmod double-asc dpeak dsel dsp_add dstat d-u dwin euclid_format euclid_unformat fbgammamod f-d fence fhor f-i g-adrt g-euclid1 g-jack globe g-off i-a i-d i-f ihist imod istat jack-g kurt lowp molecule nmgmodel nmg-sgp off-g pipe pipetest pix2g pix3filter pixcount pixelswap pixembed pixfields pixfieldsep pixflip-fb pixpaste pix-spm pix-yuv plstat pyramid rawbot remapid rlesortmap rletovcr room rtcell rtexample rtfrac rtrad rtsil rtsrv script-tab sketch solshoot sphflake spltest spm-fb ssampview syn tea tea_nmg testfree texturescale torii ttcp tube txyz-pl u-a u-bw u-d u-f umod ustat vcrtorle vegitation wall wdb_example xbmtorle xyz-pl yuv-pix

This task involves writing a (very) simple stub document holder for each of those commands in the Docbook format. The commands only need to provide a one or two sentence summary of their purpose (which is usually already written in their source files) with a basic usage statement.

Time: < 4 days

Code:

  • doc/docbook/system/man1/en/Makefile.am
  • doc/docbook/system/man1/en/*.xml

Outreach


Tasks related to community management and outreach/marketing

Write solicitation for new website designer

The BRL-CAD website is in need of a design overhaul.

This task involves writing up a brief article soliciting new contributor(s) to work on designing a new website. The article needs to be detailed and specific to our particular website requirements (Drupal+Mediawiki+CSS) to ensure the contributor can design the appropriate stylesheet(s), updated graphics, and new layout.

Time: < 2days

References:

Model new BRL-CAD Logo using BRL-CAD

The winner of the recent BRL-CAD Logo contest is a clean depiction of two interlocked components. Modeling the new Logo in BRL-CAD without using NURBS would require some careful arrangement, but would provide an attractive three dimensional rendering.

The output of this task would be a .asc file of BRL-CAD geometry (converted via g2asc) for inclusion in the db/ example directory. Optimally, the two segments would overlap at the join, but this is your opportunity as an artist and 3D magician to shine with your interpretation.

Time: < 2 days

References:

Write BRL-CAD News article on .deb/.rpm builds

BRL-CAD has a new maintainer, Jordi Sayol, for managing .deb and .rpm builds. Interview the developer, obtain details on how the releases are produced, what platforms are supported, etc, and write up an article for our Community Publication Portal (CPP)

The output of this task is an article added to our CPP wiki page in a final production-quality review state.

Time: < 1 day

References:

Write a BRL-CAD model showcase article

BRL-CAD has several geometry models developed by community members that showcase the power and applicability of BRL-CAD to various domains. For this task, you'd be expected to interview one or more individuals to obtain information and pictures about their project, write up a descriptive overview of their model, the goals of the project, and any interesting ancillary information that may be relevant. There are presently several candidate topics listed in our Community Publication Portal (CPP).

The output of this task is an article added to our CPP wiki page in a final production-quality review state.

Time: < 2 days

References:

Design a "Commercial CAD Comparison" diagram

New users frequently ask how BRL-CAD compares to other major commercial CAD systems such as CATIA, Unigraphics/NX, Pro/ENGINEER, Solidworks, and AutoCAD. BRL-CAD has many of the same features and it would be very useful to visualize the feature overlap graphically with a diagram.

This task involves identifying core significant features of relevance and describing BRL-CAD along with the various major CAD vendors. The diagram should fit on one page.

Time: <2 days

References:


Quality Assurance


Tasks related to testing and ensuring code is of high quality

Develop an N-Manifold Geometry (NMG) testing framework

BRL-CAD implements polygonal facetted geometry as "NMG" geometry, which is then used for converting from an implicit constructive solid geometry (CSG) representation to a mesh format. This is a huge portion of BRL-CAD's core libraries that is used by dozens of tools and commands so there is a need for improved robustness.

This task involves custom scripting or using a testing framework (such as googletest) that attempts to convert all of BRL-CAD's provided sample geometry into NMG format. There are more than 500 functions in the NMG code, so this task only exercises the NMG code indirectly through one of BRL-CAD's numerous geometry exporters such as g-nmg or g-dxf. The testing should report which objects do not successfully convert and percentage conversion success.

Time: <2 days

Files:

  • db/*.g
  • src/conv/g-nmg

References:

Create comprehensive utility library (LIBBU) API unit tests

There are more than 300 library functions in our core LIBBU library. As a core library used by nearly every one of BRL-CAD's tools, testing those functions for correct behavior is important.

This task involves implementing a testing framework for LIBBU that exercises every single one of the public API C function calls and reports whether tests pass successfully or not.

Code:

  • include/bu.h
  • src/libbu

References:

Time: <3 days

Create comprehensive numerics library (LIBBN) API unit tests

There are more than 300 library functions in our core LIBBN library. As a core library used by nearly every one of BRL-CAD's tools, testing those functions for correct behavior is important.

This task involves implementing a testing framework for LIBBN that exercises every single one of the public API C function calls and reports whether tests pass successfully or not.

Time: <3 days

Code:

  • include/bn.h
  • include/plot3.h
  • include/vmath.h
  • src/libbn

References:

Create a comprehensive unit test for bn_dist_pt3_pt3()

There are more than 300 library functions in our LIBBN numerics library. Creating a comprehensive unit test involves exhaustively exploring all possible inputs to the function, testing them for proper behavior, and characterizing the output in a PASS/FAIL fashion.

Unlike the other testing framework tasks, the goal of this task is comprehensiveness. The task must cover all possible inputs including NULL, -inf, +inf, NaN, real numbers, and other values in most if not all possible combinations.

Time: <2 days

Code:

  • include/bn.h
  • src/libbn

References:

Find, reproduce, confirm, and report any bug in Archer

Archer is our new modeling interface and a soon-to-be replacement for our long-standing MGED geometry editor. It undoubtedly has bugs. It's your job to find them, but do so in a manner that is so obvious that one of the other devs will be able to instantly reproduce the bug given your instructions. Crashing bugs are best, but may require learning how to use the tool with minimal documentation.

This task involves filing a bug report with verifiable and reproducible steps that clearly demonstrate the bug. It can't be a bug already reported or otherwise documented.

References:


Research


Tasks related to studying a problem and recommending solutions

Investigate performance of setting thread affinity

BRL-CAD's raytrace library (LIBRT) is pervasively multithreaded using routines defined in our basic utility library (LIBBU) for detecting an using multiple CPUs/cores/threads.

This task involves making minor modifications to the LIBBU parallel interface using sched_setaffinity and/or pthread_attr_setaffinity_np (or similar affinity mechanism depending on the platform) and then evaluating the performance impact using our BRL-CAD Benchmark suite ('benchmark' command).

Time: <2 days

Code:

  • src/libbu/parallel.c
  • src/libbu/semaphore.c

Determine why solids.sh fails on 64-bit

BRL-CAD has a regression test script called solids.sh that creates a bunch of primitives, renders an image of those primitives, and then compares that image to a reference image. On (most?) 64-bit platforms, the test is off by several RGB values for exactly 3 pixels.

This task involves figuring out why, exactly, this is occurring. It may be helpful to compare intermediate computation results from a 32-bit environment to see where the computations diverge, however slightly. Ultimately, the goal is to identify the cause and a recommended course of action to fix the divergence problem.

Time: <2 days

Code:

  • regress/solids.sh

Investigate permuted vertex lists from g-iges + iges-g

BRL-CAD has a geometry exporter and importer for the International Graphics Exchange Standard (IGES) file format. If you run our g-iges exporter on some geometry, then run iges-g on that same geometry to import it back to BRL-CAD format, the geometry will have permuted vertex lists. Particularly for geometry already in polygonal format, such as our NMG or BoT geometry, this conversion should result in identical geometry but presently does not.

This task involves investigating why this occurs, reporting (in detail) why it occurs, and if obvious, making a recommendation on how to fix the problem.

Time: <4 days

Code:

  • src/conv/iges

Investigate GMP integration

BRL-CAD uses a fastf_t typedef for most all math operations that is usually a "double" floating point type. We would like to provide the option for resorting to exact arithmetic if possible by merely redefining fastf_t to a C++ type sufficiently overloaded to behave the same.

This task would involve implementing a C++ class with overloaded operators such that vmath macro calls still work as well as a sampling of LIBBN API function calls without major changes to the original code. A perfect example case study would be creating the class then testing whether bn_dist_pt3_pt3() and bn_mat_determinant() compute correctly for values that cannot be exactly represented with floating point arithmetic.

Time: <3 days

Code:

  • include/vmath.h
  • include/bn.h

References:

Investigate the status of our command spreadsheet

We have a spreadsheet filled with information about all of BRL-CAD's 400+ commands including details about what command line options, inputs, and outputs are supported. The spreadsheet is not complete, however, and hasn't been reviewed in a couple years.

This task involves comprehensively going over the 400+ rows of the spreadsheet to systematically verify that the information is complete and correct, and to fill in missing information where needed. This task requires strong familiarity with the UNIX command line, manual pages, and how to pipe input to/from applications in a variety of formats.

Time: <3 days

Code:

  • src/ .. everywhere

References:

  • Existing spreadsheet available on request

Training


Tasks related to helping others learn more

LIBBU Doxygen cleanup

BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output. There are approximately 300 documented API function calls in LIBBU.

This task involves cleaning up the Doxygen comments in the library so that useful reports and API documentation is automatically generated (correctly and completely).

Time: <1 day

Code:

  • include/bu.h
  • src/libbu
  • misc/Doxyfile
  • ./configure --enable-documentation

References:

LIBBN Doxygen cleanup

BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output. There are approximately 300 documented API function calls in LIBBN.

This task involves cleaning up the Doxygen comments in the library (i.e., all of the /** */ comments) so that useful reports and API documentation is automatically generated (correctly and completely). The comments should be cleanly wrapped to column 70 with minimal or no embedded leading whitespace.

Time: <2 days

Code:

  • include/bn.h
  • include/plot3.h
  • include/vmath.h
  • src/libbn
  • misc/Doxyfile
  • ./configure --enable-documentation

References:

LIBWDB Doxygen cleanup

BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output. There are approximately 100 documented API function calls in LIBWDB.

This task involves cleaning up the Doxygen comments (i.e., all of the /** */ comments) in the library so that useful reports and API documentation is automatically generated (correctly and completely). The comments should be cleanly wrapped to column 70 with minimal or no embedded leading whitespace.

Time: <2 days

Code:

  • include/wdb.h
  • include/raytrace.h
  • src/libwdb
  • misc/Doxyfile
  • ./configure --enable-documentation

References:

LIBRT Doxygen cleanup

BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output. There are approximately 1000 documented API function calls in LIBRT.

This task involves cleaning up the Doxygen comments (i.e., all of the /** */ comments) in the library so that useful reports and API documentation is automatically generated (correctly and completely). The comments should be cleanly wrapped to column 70 with minimal or no embedded leading whitespace.

Time: <4 days

Code:

  • include/raytrace.h
  • src/librt
  • src/librt/primitives
  • src/librt/comb
  • src/librt/binunif
  • misc/Doxyfile
  • ./configure --enable-documentation

References:

"Introduction to BRL-CAD Tutorial"

BRL-CAD includes an extensive introduction to MGED tutorial series, but not a succinct introduction to BRL-CAD (the suite).

This task involves writing a brief introduction to BRL-CAD that highlights 10-20 of the core commands through an instructive tutorial. The tutorial should be brief, not exceeding 10 pages total.

Time: <2 days

Write a "BRL-CAD Ray Tracing Shaders" tutorial

BRL-CAD includes numerous shaders that let you specify different optical effects during ray tracing.

This task involves writing a brief tutorial that describes what shaders are and how one specifies them for geometry. How shaders are specified is already described in detail in the Introduction to MGED document.

Time: <4 days

Code:

  • src/liboptical/sh_*.c (for available shader names and corresponding options)

References:


User Interface


Tasks related to user experience research or user interface design and interaction

Design an MGED command spreadsheet

BRL-CAD's primary solid geometry modeling application is called MGED. MGED contains a comprehensive set of more than 700 commands for manipulating, viewing, and inspecting geometry. There is a need to more effectively manage those commands, characterize them all, and get a "big picture" of the command landscape so that usability may be addressed.

This task involves designing a spreadsheet that will be used to characterize all of MGED's commands.

Time: <2 days

References:

  • An existing spreadsheet already being used for BRL-CAD (i.e., non-MGED) commands is available.

Create prototype 2D CAD drawing(s)

BRL-CAD provides limited services for drafting features including the production of 2D CAD drawings (blueprints).

This task involves designing a 2D CAD drawing prototype that effectively captures a set of design requirements and follows industry conventions. Basically, this requires identifying one or more style(s) of drawings that should be supported along with critical elements to be included on each drawing.

Time: <3 days

References:

Create prototype CAD GUI layout diagram

BRL-CAD's usability is notoriously complex and "expert friendly". MGED and Archer are the main geometry editors, with drastically different user interfaces.

This task involves evaluating the features provided by MGED and Archer, then designing a new GUI layout that encompasses their features while improving usability. Rationale for design decisions and layout should be provided.

Time: < 5 days

References:

Reorganize MGED menu

BRL-CAD's main graphical user interface, MGED, is heavily menu-driven but not exceptionally well organized. This task involves performing an exhaustive review of MGED's various menus, including temporary menus when in a given editing state, reorganizing them for logical groupings, and rewording them for clarity. It's necessary to learn the basics of the MGED interface in order to understand what the various options do.

For this task, you'll provide a description of the existing menus and mapping to a new organization including basic rationale behind any new groupings or rewording.

Time <2 days

References:

Categorize all of BRL-CAD's commands into a spreadsheet

BRL-CAD is a suite of more than 400 processing tools, image tools, geometry converters, and more. There is an existing spreadsheet that characterizes all of the available commands in terms of inputs, outputs, and options, but there is insufficient characterization of BRL-CAD's commands as to how they logically group and work together.

This task involves building up a spreadsheet that lists all of our commands, describing a finite set of command categories, and characterizing all commands into those categories while filling in the spreadsheet with details for each command.

Time: <4 days

References:

  • A spreadsheet template will be provided.