Difference between revisions of "Contributor Quickies"

(no longer editing "actively")
(Add docbook man page item)
Line 1: Line 1:
 
 
The list of possible GCI projects below should serve as a good starting point for new contributors that would like to get involved in working on BRL-CAD.  Each project is roughly sorted by difficulty as EASY, MEDIUM, or HARD and categorized by type of work.  The tasks range from the very hard and math intense to tedious and VERY easy.  Also listed are requirements and a rough estimate of time needed to complete the task.  Note that the requirements are not prerequisites but skills that are necessary to complete the task.  The time estimate only presumes you have a few (ideal) hours a day.
 
The list of possible GCI projects below should serve as a good starting point for new contributors that would like to get involved in working on BRL-CAD.  Each project is roughly sorted by difficulty as EASY, MEDIUM, or HARD and categorized by type of work.  The tasks range from the very hard and math intense to tedious and VERY easy.  Also listed are requirements and a rough estimate of time needed to complete the task.  Note that the requirements are not prerequisites but skills that are necessary to complete the task.  The time estimate only presumes you have a few (ideal) hours a day.
  
Line 118: Line 117:
 
* Familiarity with word processing software
 
* Familiarity with word processing software
 
* Basic familiarity with MGED
 
* 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.
 +
 +
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.
 +
 +
References:
 +
 +
* Current Docbook man pages: http://brlcad.svn.sourceforge.net/viewvc/brlcad/brlcad/trunk/doc/docbook/system/
 +
* Docbook documentation: http://www.docbook.org/tdg/en/html/docbook.html
 +
* Doclifter conversion tool: http://www.catb.org/~esr/doclifter/
 +
* Emacs editor: http://www.gnu.org/software/emacs/emacs.html
 +
* nxml Emacs mode: http://www.thaiopensource.com/nxml-mode/
 +
 +
Time:
 +
< 4 Days
 +
 +
Requirements:
 +
* 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 ==
 
== MEDIUM: Write a "BRL-CAD Commands Quick Reference" document ==
Line 149: Line 169:
  
 
----
 
----
 +
 
=Outreach=
 
=Outreach=
 
----
 
----

Revision as of 00:37, 1 November 2010

The list of possible GCI projects below should serve as a good starting point for new contributors that would like to get involved in working on BRL-CAD. Each project is roughly sorted by difficulty as EASY, MEDIUM, or HARD and categorized by type of work. The tasks range from the very hard and math intense to tedious and VERY easy. Also listed are requirements and a rough estimate of time needed to complete the task. Note that the requirements are not prerequisites but skills that are necessary to complete the task. The time estimate only presumes you have a few (ideal) hours a day.

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.

Code


Tasks related to writing or refactoring code

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.

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

Code:

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

Time: <1 day

Requirements:

  • Rudimentary familiarity with C
  • Basic familiarity with a text editor (copy-paste)

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.

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

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

Time: <4 days

Requirements:

  • Rudimentary familiarity with C
  • Basic familiarity with a text editor (copy-paste)

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.

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.

Code:

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

Time: <2 days

Requirements:

  • Familiarity with C source code
  • Familiarity with compiling on Windows

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.

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.

Code:

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

Time: <3 days

Requirements:

  • Familiarity with C source code
  • Basic familiarity with autoconf/automake/libtool build system

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.

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)

Requirements:

  • Familiarity reading and writing C source code
  • Basic familiarity with BRL-CAD's MGED

Documentation


Tasks related to creating/editing documents

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.

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.

References:

Time: <2 days

Requirements:

  • 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.

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.

References:

Time: < 4 Days

Requirements:

  • 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.

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

References:

Time: <3 days

Requirements:

  • 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.

References:

Time: <4 days

Requirements:

  • In-depth familiarity with BRL-CAD

Outreach


Tasks related to community management and outreach/marketing

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.

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.

References:

Time: <2 days

Requirements:

  • Basic familiarity with multiple commercial CAD software packages
  • Basic familiarity with BRL-CAD

Quality Assurance


Tasks related to testing and ensuring code is of high quality

EASY: 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.

Files:

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

References:

Time: <2 days

Requirements:

  • Basic familiarity with scripting or a testing framework

MEDIUM: Create comprehensive utility library (LIBBU) API 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

Requirements:

  • Basic familiarity with C
  • Familiarity with scripting or a testing framework

MEDIUM: Create comprehensive numerics library (LIBBN) API test cases

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.

Code:

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

References:

Time: <3 days

Requirements:

  • Basic familiarity with C
  • Familiarity with scripting or a testing framework

Research


Tasks related to studying a problem and recommending solutions

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.

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.

Code:

  • regress/solids.sh

Time: <2 days

Requirements:

  • Familiarity compiling and debugging C code
  • Access to a 64-bit platform

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.

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.

Code:

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

References:

Time: <3 days

Requirements:

  • Familiarity with C
  • Familiarity with GMP
  • Basic familiarity with (BRL-CAD's) LIBBN

Training


Tasks related to helping others learn more

VERY EASY: 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).

Code:

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

References:

Time: <1 day

Requirements:

  • 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.

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.

Code:

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

References:

Time: <2 days

Requirements:

  • 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.

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.

Code:

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

References:

Time: <2 days

Requirements:

  • 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.

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.

Code:

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

References:

Time: <4 days

Requirements:

  • Basic familiarity with Doxygen

MEDIUM: "Introduction to BRL-CAD Tutorial"

Time: <2 days

Requirements:

  • 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.

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.

Code:

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

References:

Time: <4 days

Requirements:

  • Basic familiarity with BRL-CAD
  • Basic familiarity with word processing software

Translation


Tasks related to localization

VERY EASY: Translate "BRL-CAD Overview" document

BRL-CAD has a very brief overview document written in English, encoded in the Docbook XML format (very similar to HTML). http://brlcad.org/wiki/Overview

This task involves translating that document into another language correctly while preserving the existing valid Docbook tagging.

References:

Time: <1 day

Requirements:

  • Proficiency with a second language (not Spanish or Italian)
  • Basic ability to translate technical terms from English to another language
  • Basic familiarity with Docbook formatting and word processing

MEDIUM: Translate "Principles of Effective Modeling"

BRL-CAD includes a 75 page document on effective modeling practices that is desirable to have translated to other languages. The document is stored in the Docbook XML format (which is very similar to HTML).

This task involves taking the existing Docbook XML version of the document and translating the content into another language.

References:

Time: <3 days

Requirements:

  • Proficiency with a second language
  • Basic ability to translate technical terms from English to another language
  • Basic familiarity with Docbook formatting and word processing

User Interface


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

EASY: 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.

References:

Time: <3 days

Requirements:

  • 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.

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.

References:

Time: < 5 days

Requirements:

  • Basic familiarity with BRL-CAD's MGED and Archer tools
  • Basic familiarity with software usability metrics
  • Familiarity creating a layout prototype