Editing Deuces

From BRL-CAD

Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then save the changes below to finish undoing the edit.
Latest revision Your text
Line 1: Line 1:
−
Below are tasks that are a great starting point for anyone interested in contributing to BRL-CAD.  Most tasks can be completed in just a couple hours!  '''''No prior experience with BRL-CAD is required.''''' 
+
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.
  
−
Some tasks may take longer if you aren't set up or haven't done that type before, but all they all require about the same amount of experienced effort.  Each task has a description, references, and list of files you'll probably need.  Can we make it any easier?  [https://brlcad.zulipchat.com Let us know].
+
Any requirements are listed along with any background information helpful for completing the task.
  
−
= Get Set Up =
+
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]]!
  
−
We suggest you [[Compiling|compile BRL-CAD]] yourself or, if you have trouble with that, there's a virtual image with everything preconfigured, ready to go:
+
= Code =
 +
----
 +
''Tasks related to writing or refactoring code''
 +
 
 +
== VERY EASY: 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:
 +
* http://en.wikipedia.org/wiki/Centroid
 +
* http://mathworld.wolfram.com/
  
−
# [https://sourceforge.net/projects/brlcad/files/BRL-CAD%20for%20Virtual%20Machines/ Download our BRL-CAD Virtual Machine (VM) disk image.]
+
Code:
−
# [https://www.virtualbox.org/wiki/Downloads Install VirtualBox.]
+
* src/librt/primitives/*/*.c
−
# Import the disk image, start the VM, and log in (password is "Brlcad!" without quotes).
 
−
# Run "svn up brlcad-svn-trunk" and [[Compiling#Configure_your_Build|compile]].  
 
  
−
= Pick a Task =
+
Requirements:
 +
* Basic familiarity with C
 +
* Basic familiarity with a text editor
 +
* Ability to compile BRL-CAD successfully
  
−
Once set up, select any task that sounds interesting, read the references, and [https://brlcad.zulipchat.com talk with us] for help.  Don't worry if some words are confusing.  You got this.  All tasks can be completed by '''''anyone''''' but are grouped into the following five interest categories:
+
== VERY EASY: Implement a primitive surface area function ==
  
−
* Code (programming)
+
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.
−
* Documentation and Training (technical writing)
 
−
* Outreach and Research (graphics, marketing)
 
−
* Quality Assurance (testing)
 
−
* User Interface (usability, design)
 
  
−
__TOC__
+
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
  
−
== Code ==
+
References:
−
''Tasks related to writing or refactoring code''
+
* http://en.wikipedia.org/wiki/Surface_area
 +
* http://mathworld.wolfram.com/
 +
 
 +
Code:
 +
* src/librt/primitives/*/*.c
  
−
See the When You're Done section above for details on submitting your changes.
+
Requirements:
 +
* 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 ==
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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.
−
| style="padding: 20px;" |
 
−
=== Close MGED only when both 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 run, it creates 2 windows:  a text console for commands and an interactive graphics window.  Currently, if you close the graphics window, it quits the application.
+
This task involves editing source code to move comments, cleaning up comment formatting, and verifying Doxygen output.   
  
−
This task involves change behavior so that MGED exits only after closing ''both'' windows.  Closing just the graphics window  or text console should not quit MGED.
+
Time: <1 day
  
 
Code:
 
Code:
−
* src/mged/mged.c
+
* include/bn.h
−
* src/tclscripts/mged/openw.tcl
+
* src/libbn/*.c
−
* src/tclscripts/mged/bindings.tcl
+
 
 +
Requirements:
 +
* Rudimentary familiarity with C
 +
* Basic familiarity with a text editor (copy-paste)
  
−
&nbsp;
+
== EASY: Implement a primitive volume function ==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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.
−
| style="padding: 20px;" |
 
−
=== 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 '''ell'''ipsoid.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives while others are more tricky to compute.
+
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.
  
−
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).  There are numerous examples in our code where we compute centroids for other primitives.  The primitives that do not already have a centroid callback are itemized in following.
+
Time: <1 days
  
 
References:
 
References:
−
* http://en.wikipedia.org/wiki/Centroid
+
* http://en.wikipedia.org/wiki/Volume
 
* http://mathworld.wolfram.com/
 
* http://mathworld.wolfram.com/
−
* include/raytrace.h: See ft_centroid callback defined in the rt_functab structure
 
  
 
Code:
 
Code:
−
* src/librt/primitives/table.c
+
* src/librt/primitives/*/*.c
−
* src/librt/primitives/[PRIMITIVE]/[PRIMITIVE].c
+
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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 :
 +
* 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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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. 
 +
 
 +
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
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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)
  
−
&nbsp;
+
Requirements:
−
|}
+
* Familiarity reading and writing C source code
−
&nbsp;
+
* Basic familiarity with BRL-CAD's MGED
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== HARD: Fix Bounding Box function for BoT primitive ==
−
| style="padding: 20px;" |
 
−
=== Implement a primitive curvature function ===
 
  
−
BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones each described by a collection of callback functions, for example rt_'''sph'''_bbox() returns the bounding box dimensions for a '''sph'''ere.  Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives while others are a little more tricky to compute.
+
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 writing the callback function rt_xxx_curve() that computes the curvature at a given point on the surface of a primitive such as;
+
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.
−
* superell
 
−
* cline
 
−
* extrude
 
−
* grip
 
−
* metaball
 
−
* hrt.   
 
−
There are numerous examples in our code where we compute the curvature for other primitives like the ellipsoid, sphere, elliptical parabola, etc.
 
  
−
References:
+
Time: <4 days
−
* http://en.wikipedia.org/wiki/Curvature
 
−
* http://en.wikipedia.org/wiki/Radius_of_curvature_(mathematics)
 
−
* http://mathworld.wolfram.com/
 
−
* include/raytrace.h: See the data structure that holds the curvature of a surface at a point (from Line 296) as well as the prototype for ft_curve() callback function defined in the rt_functab structure ( Line 2078).
 
  
 
Code:
 
Code:
−
* src/librt/primitives/table.c
+
* src/librt/primitives/bot/bot.c (the rt_bot_bbox function)
−
* src/librt/primitives/[PRIMITIVE]/[PRIMITIVE].c
 
  
−
&nbsp;
+
Requirements:
−
|}
+
* Familiarity reading and writing C source code
−
&nbsp;
+
* Basic familiarity with BRL-CAD's MGED
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== HARD: Implement a primitive UV-mapping callback ==
−
| style="padding: 20px;" |
 
−
=== 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 '''ell'''ipsoid.  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.  Note that this is an advanced task that might take you more than a couple hours if you don't have solid coding skills, but it's ultimately just a few lines of code.  See other primitives that already implement a UV-mapping callback for reference.
+
This task involves implementing a UV-mapping callback for any of the primitives that do not already have a functional UV-callback defined.
  
−
References:
+
Time: <3 days
−
* http://en.wikipedia.org/wiki/UV_mapping
 
−
* src/librt/primitives/[PRIMITIVE]/[PRIMITIVE].c, search for rt_*_uv() functions
 
  
 
Code:
 
Code:
−
* src/librt/primitives/extrude/extrude.c
+
* src/librt/primitives/*/*.c
 
* src/librt/primitives/table.c
 
* src/librt/primitives/table.c
 
* include/rtgeom.h
 
* include/rtgeom.h
  
−
&nbsp;
+
References:
−
|}
+
* http://en.wikipedia.org/wiki/UV_mapping
−
&nbsp;
 
  
 +
Requirements:
 +
* Familiarity writing C source code
 +
* Basic familiarity with UV-mapping
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
----
−
| style="padding: 20px;" |
 
−
=== Fix elliptical torus triangulation ===
 
  
−
BRL-CAD has many 3D object types, one of them being an "Elliptical Torus".  If you create a new MGED database and run this sequence of commands, it'll crash due to excessive recursion:
+
=Documentation=
 +
----
 +
''Tasks related to creating/editing documents''
  
−
<pre>
+
== EASY: Add missing documentation (for JUST ONE command) ==
−
make eto eto
 
−
tol norm 1
 
−
facetize eto.bot eto
 
−
</pre>
 
  
−
This task's goal is to reproduce, identify, and fix the bug so that detailed eto tessellation completes successfully.  To get started, see the rt_eto_tess() function in src/librt/primitives/eto/eto.c and the facetize command logic in libged.
+
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:
 
Code:
−
* src/librt/primitives/eto/eto.c, <- you'll probably need to modify this file
+
* doc/docbook/system/man1/en/Makefile.am
−
* src/libged/facetize/facetize.cpp
+
* doc/docbook/system/man1/en/*.xml
  
−
&nbsp;
+
Requirements:
−
|}
+
* Basic familiarity with using a text editor
−
&nbsp;
+
* 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)
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: Write "MGED Interface" reference document==
−
| style="padding: 20px;" |
 
−
=== Implement a function that evaluates volume with spherical sampling ===
 
  
−
Implement this function:
+
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.
  
−
    int estimate_volume(struct db_i *dbip,  
+
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 [http://brlcad.org/w/images/8/8c/Shift_Grips_Quick_Reference_Guide.pdf shift grips reference] should be incorporated, albeit much more concisely and organized.
−
                        struct directory *dp,
 
−
                        size_t min_samples,
 
−
                        double confidence);
 
  
−
For this function, you'll want to read up on some of BRL-CAD's basic data structures by looking at headers in the include/rt directory or by reading our [https://brlcad.org/docs/api/ API documentation].  Calling rt_db_internal() and rt_bound_internal() will get you the bounding box around geometry from which you can calculate a bounding sphere.  Once you have the bounding sphere, randomly generate a set of min_samples*2 points on the surface of the sphere.  Shoot a ray through those points using rt_shootray(), as in the ray tracing [[Example_Application|example]].  Keep track of a volume estimate and keep shooting sets of min_samples rays until the estimate is less than the specified confidence value.  Volume of a sphere is (4/3 * pi * r^3) so dividing that by num_samples will give a per-ray factor and multiplying all hit thicknesses by that factor will give a running volume estimate.
+
Time: <2 days
  
 
References:
 
References:
−
* https://brlcad.org/docs/api/
+
* http://brlcad.org/wiki/Documentation
−
* https://brlcad.org/wiki/Example_Application
+
* http://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf
−
* https://stackoverflow.com/questions/9600801/evenly-distributing-n-points-on-a-sphere
+
* http://brlcad.org/w/images/8/8c/Shift_Grips_Quick_Reference_Guide.pdf
−
* https://karthikkaranth.me/blog/generating-random-points-in-a-sphere/
+
* http://www.audioease.com/Pages/Altiverb/features/2small.jpg
  
−
&nbsp;
+
Requirements:
−
|}
+
* Familiarity with word processing software
−
&nbsp;
+
* Basic familiarity with MGED
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== MEDIUM: Convert src/conv man pages to valid Docbook  ==
−
| style="padding: 20px;" |
 
  
−
=== Implement a function to return an object's color ===
+
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.
  
−
CAD geometry can have colors specified in a number of ways including directly on that object, in a parent object, and in a lookup table.  For this task, you're going to implement a function that reports the color of an object given a path to that object:
+
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.
  
−
    int get_color(struct db_i *dbip, const char *path, struct bu_color *rgb);
+
Time: <4 days
  
−
You'll need to iteratively consider each object named on the specified path (e.g., "/car/wheel/tire.r/torus") starting with "car" and working your down the path (i.e., 'wheel', 'tire.r', and then 'torus') to 1) see if a color is set on that object and 2) see if that color overrides lower-level colors (i.e., is inherited down the path), and 3) if it's a region object, whether there is a color set in the region table. You'll need to db_lookup() each object on the path to get access to its data.
+
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/
  
−
For this function, you'll want to read up on some of BRL-CAD's basic data structures by looking at headers in the include/rt directory or by reading our [https://brlcad.org/docs/api/ API documentation].  This task may seem complicated if you're not familiar with C/C++ APIs, data structures, or hierarchical paths, so don't be shy [https://brlcad.zulipchat.com asking] questions.
+
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.
  
−
References:
+
== MEDIUM: Write a "BRL-CAD Commands Quick Reference" document ==
−
* https://brlcad.org/docs/api/
 
  
−
Code References:
+
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.
−
* src/libged/display_list.c
 
−
* src/libged/color/color.c
 
−
* src/librt/prep.c
 
  
−
&nbsp;
+
This task involves writing a quick reference document similar to [http://brlcad.org/w/images/5/52/MGED_Quick_Reference_Card.pdf the MGED quick reference] but for BRL-CAD commands.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Time: <3 days
−
| style="padding: 20px;" |
 
  
−
=== Stub in an OpenVDB object ===
+
References:
 +
* http://brlcad.org/wiki/Documentation
 +
* http://brlcad.org/w/images/5/52/MGED_Quick_Reference_Card.pdf
  
−
BRL-CAD has dozens of distinct primitive object types.  For this task, you're going to implement the bare minimum to necessary to create a new object with the "make" command in MGED.
+
Requirements:
 +
* Familiarity with layout software
 +
* Basic familiarity with BRL-CAD
  
−
The best way to achieve this task is by searching for a keyword for another primitive (e.g., 'grep -r -i superell .') and implementing your new object the same way.  Start with the 'make' command itself in src/libged/make/make.c and add "vdb" alongside where you find one of the other primitive types (e.g., superell).  To get that to compile, you'll have to add new symbols you've defined into header files (e.g., include/rt/rtgeom.h).  You'll eventually need to implement barebones logic in src/librt/primitives/vdb too.
+
== HARD: Write a "Technical Overview of BRL-CAD" document ==
  
−
Code:
+
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.
−
* include/rt/defines.h <- needs an ID
 
−
* include/rt/geom.h <- needs an "internal" i.e., in-memory structure
 
−
* src/libged/make/make.c <- needs to recognize "vdb" as a valid type
 
−
* src/librt/primitives/table.cpp <- needs an entry
 
−
* src/librt/primtiives/vdb <- needs a dir
 
−
* src/librt/primitives/vdb/vdb.c <- needs _import5/_export5 callbacks, maybe _describe too
 
  
−
&nbsp;
+
Time: <4 days
−
|}
 
−
&nbsp;
 
  
−
== Documentation and Training ==
+
References:
 +
* http://brlcad.org/d/about
 +
* http://brlcad.org/wiki/Overview
  
−
''Tasks related to creating/editing documents and helping others learn more about BRL-CAD''
+
Requirements:
 +
* In-depth familiarity with BRL-CAD
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
 
−
| style="padding: 20px;" |
+
== HARD: Add missing documentation (for ALL missing) ==
−
=== Add missing documentation (for any 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 223: Line 394:
 
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
 
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 basic documentation for '''JUST ONE''' of those commands in the Docbook XML format.  The command documentation should provide a one-sentence description, a detailed paragraph description (200+ words), explanation of '''all''' available command-line options, and one or more examples on how to use the command.  
+
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:
 
Code:
Line 229: Line 402:
 
* doc/docbook/system/man1/en/*.xml
 
* doc/docbook/system/man1/en/*.xml
  
−
&nbsp;
+
Requirements:
−
|}
+
* Basic familiarity with using a text editor
−
&nbsp;
+
* Basic familiarity writing in a tagged format (Docbook format is ''very'' similar to html) -- many examples provided
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
----
−
| style="padding: 20px;" |
 
−
=== Complete our "Intro to BRL-CAD Modeling" tutorial and extend it ===
 
  
−
We've developed two short and simple tutorials for introducing new users to modeling with BRL-CAD.
+
=Outreach=
 +
----
 +
''Tasks related to community management and outreach/marketing''
  
−
This task involves doing one of the tutorials (they take about an hour) and then extending it with a new section or making some other improvement.  At the end of the tutorial are several optional advanced "exercise left to the reader", for example.  Write a half-page step-by-step for one of the exercises left to the reader.  Include screenshots and images to make it look nice so the reader is not bored.
+
== EASY: Write solicitation for new website designer ==
  
−
Reference:
+
The BRL-CAD website is in need of a design overhaul.
−
* Come [https://brlcad.zulipchat.com talk with us] to make sure you get a copy of the latest version.
 
−
* https://brlcad.org/w/images/9/90/Intro_to_BRL-CAD.pdf
 
−
* https://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf
 
−
* ... there's another new one, but you have to ask for it ...
 
  
−
&nbsp;
+
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.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Time: < 2days
−
| style="padding: 20px;" |
 
  
−
=== Translate "Contributors Guide To BRL-CAD" To Any Language ===
+
References:
 +
* http://brlcad.org
  
−
People interested in improving BRL-CAD sometimes find themselves lost in a sea of information. In all, BRL-CAD has more than a million words of documentation across hundreds of manual pages, dozens of tutorials and examples, hundreds of wiki pages, dozens of technical papers, and other resources. There are literally thousands of features and this can sometimes pose problems.
+
Requirements:
 +
* Ability to write well, clearly, and convincingly
 +
* Basic familiarity with the BRL-CAD website
  
−
In 2013, a team of contributors got to California and worked on an entire book titled "Contributors Guide To BRL-CAD" in just a few days. This great resource needs to be translated to other languages to attract developers from other lingual backgrounds (who don't read English ) to contribute to BRL-CAD.
+
== EASY: Model new BRL-CAD Logo using BRL-CAD ==
  
−
This task involves translating the chapters/sections of the "Contributors Guide To BRL-CAD" into a language of your choice such as Mandarin, French, Chinese, Spanish, German, Hindi, Arabic, Russian, etc. Chapters/Sections include
+
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.
  
−
* Feature Overview
+
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.  
−
* Working with our Code
 
−
* What code to work on
 
−
* How to contribute
 
−
* .... (Just to name a few )
 
  
−
The output of this task can be a pdf, html, doc, odt or any other document file that contains the translated article.Images in the original document (see link in Reference below) should not be changed ! only text should be.
+
Time: < 2 days
  
−
Reference:
+
References:
−
* http://en.flossmanuals.net/_booki/contributors-guide-to-brl-cad/contributors-guide-to-brl-cad.pdf
+
* http://brlcad.org/images/angelov_256.png
 +
* http://brlcad.org/d/node/92
 +
* Introduction to MGED at http://brlcad.org/wiki/Documentation
  
−
&nbsp;
+
== EASY: Write BRL-CAD News article on .deb/.rpm builds ==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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)
−
| style="padding: 20px;" |
 
  
−
=== Write a "BRL-CAD Commands Quick Reference" document ===
+
The output of this task is an article added to our CPP wiki page in a final production-quality review state.
  
−
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.
+
Time: < 1 day
 +
 
 +
References:
 +
* http://brlcad.org/wiki/Community_Publication_Portal
 +
 
 +
Requirements:
 +
* 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).
 +
 
 +
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:
 +
* http://brlcad.org/wiki/Community_Publication_Portal
 +
 
 +
Requirements:
 +
* 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.
  
−
This task involves writing a quick reference document similar to [http://brlcad.org/w/images/5/52/MGED_Quick_Reference_Card.pdf the MGED quick reference] but for BRL-CAD commands.  The sheet should minimally include the following commands:
+
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.
  
−
mged, rt*, *-g, g-*, fb*, *fb, nirt, remrt, rtsrv, asc2g, g2asc, dbupgrade, pix*, *pix, *-*, brlman, benchmark
+
Time: <2 days
  
 
References:
 
References:
−
* http://brlcad.org/wiki/Documentation
+
* http://brlcad.org/Industry_Diagram.png
−
* http://brlcad.org/w/images/5/52/MGED_Quick_Reference_Card.pdf
+
* Example feature comparisons (although not a diagram): http://en.wikipedia.org/wiki/Comparison_of_3D_computer_graphics_software
−
* [http://appletree.or.kr/quick_reference_cards/CVS-Subversion-Git/git-cheat-sheet-large.png git example]
+
* Additional feature comparisons (also not a diagram): http://en.wikipedia.org/wiki/Comparison_of_CAD_editors_for_CAE
−
* [http://www.stdout.org/~winston/latex/latexsheet-0.png latex example]
+
 
−
* [http://img.docstoccdn.com/thumb/orig/524314.png another example]
+
Requirements:
−
* [http://www.inmensia.com/files/pictures/internal/CheatSheetDrupal4.7.png drupal example]
+
* Basic familiarity with multiple commercial CAD software packages
−
* [http://www.phpmagicbook.com/wp-content/uploads/2010/06/php-reference-card.jpg php example]
+
* Basic familiarity with BRL-CAD
 +
 
 +
----
 +
 
 +
=Quality Assurance=
 +
----
 +
''Tasks related to testing and ensuring code is of high quality''
  
−
&nbsp;
+
== EASY: Develop an N-Manifold Geometry (NMG) testing framework==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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.
−
| style="padding: 20px;" |
 
  
−
=== Doxygen cleanup ===
+
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.
  
−
BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.
+
Time: <2 days
  
−
This task involves cleaning up the Doxygen comments in the library so that useful reports and API documentation automatically generated (correctly, completely, and cleanly). Verify/fix any Doxygen syntax.  Verify/fix groups so that functions are organized neatly and all contained within a group.  Provide patches that give clean (PDF) output from Doxygen.
+
Files:
 +
* db/*.g
 +
* src/conv/g-nmg
  
 
References:
 
References:
−
* http://www.jiggerjuice.net/software/doxygen.html
+
* http://en.wikipedia.org/wiki/Topological_manifold
−
* http://www.stack.nl/~dimitri/doxygen/starting.html
+
* http://en.wikipedia.org/wiki/Constructive_solid_geometry
−
* http://www.stack.nl/~dimitri/doxygen/
+
* http://code.google.com/p/googletest/
 +
 
 +
Requirements:
 +
* Basic familiarity with scripting or a testing framework
  
−
&nbsp;
+
== MEDIUM: Create comprehensive utility library (LIBBU) API unit tests ==
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 2px;" width="100%"
+
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.
−
| style="padding: 10px;" |
 
−
==== ... doxygen cleanup for LIBBU ====
 
  
−
There are approximately 300 documented API function calls in LIBBU.
+
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:
 
Code:
 
* include/bu.h
 
* include/bu.h
 
* src/libbu
 
* src/libbu
−
* misc/Doxyfile
 
  
−
&nbsp;
+
References:
−
|}
+
* http://code.google.com/p/googletest/
−
&nbsp;
+
 
 +
Time: <3 days
 +
 
 +
Requirements:
 +
* 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.
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 2px;" width="100%"
+
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.
−
| style="padding: 10px;" |
 
−
==== ... doxygen cleanup for LIBWDB ====
 
  
−
There are approximately 100 documented API function calls in LIBWDB.
+
Time: <3 days
  
 
Code:
 
Code:
−
* include/wdb.h
+
* include/bn.h
−
* include/raytrace.h
+
* include/plot3.h
−
* src/libwdb
+
* include/vmath.h
−
* misc/Doxyfile
+
* src/libbn
 +
 
 +
References:
 +
* http://code.google.com/p/googletest/
 +
 
 +
Requirements:
 +
* Basic familiarity with C
 +
* Familiarity with scripting or a testing framework
 +
 
 +
== MEDIUM: Create a comprehensive unit test for bn_dist_pt3_pt3() ==
  
−
&nbsp;
+
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.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 2px;" width="100%"
+
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.
−
| style="padding: 10px;" |
 
−
==== ... doxygen cleanup for LIBRT ====
 
  
−
There are approximately 1000 documented API function calls in LIBRT.
+
Time: <2 days
  
 
Code:
 
Code:
−
* include/raytrace.h
+
* include/bn.h
−
* src/librt
+
* src/libbn
−
* src/librt/primitives
 
−
* src/librt/comb
 
−
* src/librt/binunif
 
−
* misc/Doxyfile
 
  
−
&nbsp;
+
References:
−
|}
+
* http://code.google.com/p/googletest/
−
&nbsp;
 
  
−
&nbsp;
+
Requirements:
−
|}
+
* Basic familiarity with unit testing
−
&nbsp;
+
* Strong critical thinking skills
 +
* Basic familiarity with C
 +
* Familiarity with scripting or a testing framework
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: Find, reproduce, confirm, and report any bug in Archer ==
−
| style="padding: 20px;" |
 
−
=== Add images to our wiki page on Volumetric objects ===
 
  
−
BRL-CAD provides a couple dozen distinct primitives.  Each primitive is defined by a set of parameters.  Several of the more complex primitives have a wiki page describing them in more detail with an example on how to create them.
+
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 adding images to our page for the VOL primitive.  You'll need to first complete the tutorial and save images for each step.  Add the images to the wiki page.
+
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:
 
References:
−
* http://brlcad.org/wiki/VOL
+
* archer
−
* http://brlcad.org/wiki/DSP
+
* Introduction to MGED at http://brlcad.org/wiki/Documentation (many of the mged commands are available in some fashion within archer)
−
* http://brlcad.org/wiki/Sketch
+
* BUGS file in any source/binary distribution
−
* http://brlcad.org/wiki/EBM
+
* http://sourceforge.net/tracker/?atid=640802&group_id=105292&func=browse
  
−
&nbsp;
+
----
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
=Research=
−
| style="padding: 20px;" |
+
----
−
=== Fix Image Formatting in BRL-CAD's DocBook Documentation (any ONE large document or 4 smaller documents) ===
+
''Tasks related to studying a problem and recommending solutions''
  
−
The majority of BRL-CAD's documentation is defined as DocBook files, from which other formats (HTML, PDF, man page, etc.) can be generated.  PDF files present a particular challenge, and have some very specific requirements to achieve "good" formatting.
+
== EASY: Investigate performance of setting thread affinity ==
  
−
BRL-CAD's DocBook files need to uniformly use a style of image inclusion that is aware of what "role" the image is supposed to serve.   A "basic" image inclusion example looks like this:
+
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.
  
−
  <mediaobject>
+
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).
−
    <imageobject>
 
−
      <imagedata align="center" fileref="../../lessons/en/images/img.png" format="PNG"/>
 
−
    </imageobject>
 
−
    <nowiki><caption></nowiki>
 
−
      <para>
 
−
        Caption goes here.
 
−
      </para>
 
−
    </caption>
 
−
  </mediaobject>
 
  
−
This task involves switching image inclusions that use the above style to something like the following:
+
Time: <2 days
  
−
  <mediaobject>
+
Code:
−
    <imageobject role="html">
+
* src/libbu/parallel.c
−
      <imagedata align="center" fileref="../../books/en/images/img.png" format="PNG"/>
+
* src/libbu/semaphore.c
−
    </imageobject>
 
−
    <imageobject role="fo">
 
−
      <imagedata align="center" fileref="../../books/en/images/img.png" format="PNG"/>
 
−
    </imageobject>
 
−
    <nowiki><caption></nowiki>
 
−
      <para>
 
−
        Caption goes here.
 
−
      </para>
 
−
    </caption>
 
−
</mediaobject>
 
−
 
−
The "role" flag to imageobject provides the opportunity to specify different image formatting options when the output is HTML (role="html") or PDF (role="fo").
 
  
−
The captions should be preserved as above on mediaobjects that have them, but mediaobjects without a caption should also be converted and there is no need to add a caption in such cases.
+
Requirements:
 +
* Basic familiarity with C code
 +
* Ability to compile and run BRL-CAD
 +
 
 +
== MEDIUM: Determine why solids.sh fails on 64-bit ==
  
−
Any patch that makes changes to the DocBook sources should result in a successful "make doc" build test.  This won't generate PDF documents, but it will validate the XML files and produce HTML - remember that introducing breakage means the patch won't be accepted.
+
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.
  
−
Remember, the tasks are simply to do the above conversion for all images in the file or files, not to introduce PDF specific formatting.  Formatting fixes will be needed, but they are very much "case by case" and will take both additional time and a working Apache FOP installation, as well as knowledge of how to enable PDF generation.  If all image inclusions have been converted successfully and a student is interested in actually fixing the formatting, please discuss it with us on IRC or the mailing list.
+
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.
  
−
References:
+
Time: <2 days
−
* doc/docbook/books/en/BRL-CAD_Tutorial_Series-VolumeIII.xml
 
  
 
Code:
 
Code:
−
* doc/docbook
+
* regress/solids.sh
 +
 
 +
Requirements:
 +
* Familiarity compiling and debugging C code
 +
* Access to a 64-bit platform
  
−
&nbsp;
+
== MEDIUM: Investigate permuted vertex lists from g-iges + iges-g ==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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.
−
| style="padding: 20px;" |
 
−
=== Find 5 bugs in OGV ===
 
  
−
Online Geometry Viewer is a web based application with which you can see 3D .g models in browser without the use of any plugins. Your task will be to deploy OGV locally and find 5 bugs or errors in it.  
+
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.
  
−
Links:
+
Time: <4 days
−
https://github.com/BRL-CAD/OGV-meteor/
 
  
−
&nbsp;
+
Code:
−
|}
+
* src/conv/iges
−
&nbsp;
 
  
−
==Outreach and Research ==
+
Requirements:
−
''Tasks related to community management, outreach/marketing, studying problems, and recommending solutions''
+
* Familiarity compiling and debugging C code
 +
* Ability to compile and run BRL-CAD's g-iges and iges-g converters
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== HARD: Investigate GMP integration ==
−
| style="padding: 20px;" |
 
−
=== Profile NURBS prep performance ===
 
  
−
BRL-CAD implements support for rendering of NURBS representation geometry.  If you import a solid 3DM or STEP format model into BRL-CAD, it will import as BREP/NURBS geometry.  Opening that geometry in BRL-CAD's MGED editor will tell you what objects are available and our 'rt' tool will raytrace it.  When geometry is ray traced, it first goes through a "prep" phase and then it starts shooting rays.  Our prep phase is entirely unoptimized so we'd like to know where all the time is presently being spent during prep..
+
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 involves importing some NURBS geometry into BRL-CAD and ray tracing that geometry with a profiler watching our prep performance.  Any profiler will do, including gprof, but a performance monitor like oprofile or the Mac "Instruments" application (or Shark) are preferred.
+
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.
  
−
Learning how to use a profiler is beyond the scope of this task, so it make take you considerably longer to provide us with useful information if you've never run a profiler before.
+
Time: <3 days
  
−
To capture prep performance, you will need to import some fairly complex geometry. You should be able to search google with "filetype:3dm" or "filetype:step" or find something on grabcad.com to import
+
Code:
 +
* include/vmath.h
 +
* include/bn.h
  
−
Running "tops" within mged will tell you what geometry is available for rendering.
+
References:
 +
* http://gmplib.org/
 +
 
 +
Requirements:
 +
* Familiarity with C
 +
* Familiarity with GMP
 +
* Basic familiarity with (BRL-CAD's) LIBBN
  
−
Running "rt -o file.png -s32" on the system command line (not inside mged) should minimize the ray overhead or you can specifically isolate the prep phase we care about.  Prep is the time between when rt is run where it opens a window until the first pixels are fired and pixels start filling in.
+
== HARD: Investigate the status of our command spreadsheet ==
  
−
&nbsp;
+
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.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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.
−
| style="padding: 20px;" |
 
−
=== Continue investigating 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. You should be proficient with C++ operator overloading to take this work on.  This task is a continuation of a prior GCI task (read it in full!):
+
Time: <3 days
  
−
http://www.google-melange.com/gci/task/view/google/gci2012/7946218
+
Code:
 +
* src/ .. everywhere
  
−
This task involves testing compilation with 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.
+
References:
 +
* Existing spreadsheet available on request
  
−
Building on the previous GCI task work, take it to the next step.  Try setting a vector to 1/3, 1/3, 1/3 and 0.1, 0.1, 0.1 and get proper values to print.  Change the V3ARGS() macro if needed.  If that all works, try to get bn_dist_pt3_pt3() to work.  Report and discuss your progress.
+
Requirements:
 +
* Basic familiarity with C, ability to recognize getopt() option strings
 +
* Familiarity with the UNIX command line
 +
* Familiarity with manual pages
  
−
&nbsp;
+
----
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
=Training=
−
| style="padding: 20px;" |
+
----
−
=== Upgrade OpenNURBS, report issues ===
+
''Tasks related to helping others learn more''
  
−
BRL-CAD uses a customized OpenNURBS library for advanced geometry but it's out of date.  For this task, you're going to download the latest OpenNURBS code and upgrade the sources we bundle.  The easiest way is probably to move src/other/openNURBS to src/other/openNURBS.backup, and then put the latest OpenNURBS release into src/other/openNURBS.
+
== VERY EASY: LIBBU Doxygen cleanup ==
  
−
Once that's done, you'll need to add the src/other/openNURBS.backup/CMakeLists.txt file and make sure the list of files it has matches the files in src/other/openNURBS.  Last but not least, re-run cmake and make sure it compiles.  You may need to consult the newer openNURBS makefile to see if there are other edits needed in the CMakeLists.txt file.
+
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.  
  
−
Save output from any commands you run because you'll probably encounter an error, and that's okay.  Just submit logs of all output so we can figure out next steps.
+
This task involves cleaning up the Doxygen comments in the library so that useful reports and API documentation is automatically generated (correctly and completely).
  
−
References:
+
Time: <1 day
−
* https://github.com/mcneel/opennurbs
 
  
 
Code:
 
Code:
−
* src/other/openNURBS <- replace existing with latest openNURBS from github
+
* include/bu.h
 +
* src/libbu
 +
* misc/Doxyfile
 +
* ./configure --enable-documentation
  
−
&nbsp;
+
References:
−
|}
+
* http://www.jiggerjuice.net/software/doxygen.html
−
&nbsp;
+
* http://www.stack.nl/~dimitri/doxygen/starting.html
 +
* http://www.stack.nl/~dimitri/doxygen/
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Requirements:
−
| style="padding: 20px;" |
+
* Basic familiarity with Doxygen
−
=== Design a T-Shirt for BRL-CAD ===
 
  
−
This task involves designing a T-Shirt for BRL-CAD. Use your designing skills to design a T-Shirt for BRL-CAD. You can use the current BRL-CAD logo, or you may tweak it. Be creative while designing this T-Shirt. It would be good if the design has some special meaning.
+
== EASY: LIBBN Doxygen cleanup ==
  
−
Logo References
+
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.
−
* [https://brlcad.org/img/logo_color.png BRL-CAD Logo]
 
  
−
&nbsp;
+
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.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Time: <2 days
−
| style="padding: 20px;" |
 
−
=== Design a coffee mug for BRL-CAD ===
 
  
−
This task involves designing a coffee mug for BRL-CAD. Make it look good or at least interesting, and make it in BRL-CAD. Look over some coffee mug designs before starting to work on this. Verify that your mug is valid geometry by running the "rtcheck" command.  
+
Code:
 +
* include/bn.h
 +
* include/plot3.h
 +
* include/vmath.h
 +
* src/libbn
 +
* misc/Doxyfile
 +
* ./configure --enable-documentation
  
−
Logo References
+
References:
−
* [https://brlcad.org/img/logo_color.png BRL-CAD Logo]
+
* http://www.jiggerjuice.net/software/doxygen.html
 +
* http://www.stack.nl/~dimitri/doxygen/starting.html
 +
* http://www.stack.nl/~dimitri/doxygen/
  
−
&nbsp;
+
Requirements:
−
|}
+
* Basic familiarity with Doxygen
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: LIBWDB Doxygen cleanup ==
−
| style="padding: 20px;" |
 
−
=== Design BRL-CAD sticker ===
 
  
−
This task involves designing a BRL-CAD sticker. The design should be simple and sleek. The concept of sticker should be clear and also it should be creatively presented. Get inspired from some sticker designs but choose your own imagination while designing the sticker. There is no bound for shape of sticker, it can be rectangular, circular or even irregular. The only thing that matters is that it should look good.
+
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.  
  
−
Logo References
+
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.
−
* [https://brlcad.org/img/logo_color.png BRL-CAD Logo]
 
  
−
&nbsp;
+
Time: <2 days
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Code:
−
| style="padding: 20px;" |
+
* include/wdb.h
−
=== Design a wallpaper / desktop image for BRL-CAD ===
+
* include/raytrace.h
 +
* src/libwdb
 +
* misc/Doxyfile
 +
* ./configure --enable-documentation
 +
 
 +
References:
 +
* http://www.jiggerjuice.net/software/doxygen.html
 +
* http://www.stack.nl/~dimitri/doxygen/starting.html
 +
* http://www.stack.nl/~dimitri/doxygen/
  
−
This task involves designing a desktop background for BRL-CAD enthusiasts.  The main idea of your wallpaper should be to showcase one or more features of BRL-CAD.  Be intentional and able to defend/describe your choice of color, layout, and other aspects of the wallpaper design.
+
Requirements:
−
+
* Basic familiarity with Doxygen
−
Try to make sure the wallpaper works across a broad selection of screen resolutions.
 
  
−
Search the web for wallpapers inspiration such as:
+
== MEDIUM: LIBRT Doxygen cleanup ==
−
* http://www.smashingmagazine.com/tag/wallpapers/
 
  
−
Logo References
+
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.
−
* [https://brlcad.org/img/logo_color.png BRL-CAD Logo]
 
  
−
&nbsp;
+
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.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Time: <4 days
−
| style="padding: 20px;" |
 
−
=== Model a Lightcycle in BRL-CAD using CSG ===
 
  
−
The movie Tron is an iconic computer graphics film that used CSG primitives for a majority of the movie's 3D virtual world. The film is famous for "lightcycle" vehicles that were allegedly modeled using 57 primitives and/or Boolean operations. For this task, see if you can recreate the masterpiece in BRL-CAD.
+
Code:
−
+
* include/raytrace.h
−
See this lightcycle discussion thread
+
* src/librt
−
* http://www.tron-sector.com/forums/default.aspx?a=top&id=336281
+
* src/librt/primitives
 +
* src/librt/comb
 +
* src/librt/binunif
 +
* misc/Doxyfile
 +
* ./configure --enable-documentation
 +
 
 +
References:
 +
* http://www.jiggerjuice.net/software/doxygen.html
 +
* http://www.stack.nl/~dimitri/doxygen/starting.html
 +
* http://www.stack.nl/~dimitri/doxygen/
 +
 
 +
Requirements:
 +
* Basic familiarity with Doxygen
  
−
&nbsp;
+
== MEDIUM: "Introduction to BRL-CAD Tutorial" ==
−
|}
 
−
&nbsp;
 
  
−
== Quality Assurance ==
+
BRL-CAD includes an extensive introduction to MGED tutorial series, but not a succinct introduction to BRL-CAD (the suite).
−
''Tasks related to testing and ensuring code is of high quality''
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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.
−
| style="padding: 20px;" |
 
−
=== Fix single-precision floating point crash ===
 
  
−
By default, all of BRL-CAD compiles using double-precision floating point arithmetic.  We provide a simple typedef, however, that converts almost the entire system over to single-precision floating point.  This compilation mode was recently cleaned up and tested, but a bug was found.  The problem is reproduced very simply by compiling in single precision mode and running our "rt" ray tracer tool.
+
Time: <2 days
  
−
To compile in single precision, edit the include/bn.h header file and change the fastf_t typedef from double to float.  To reproduce the bug, compile BRL-CAD and write this out to a text file named star.view:
+
Requirements:
 +
* Familiarity with layout software
 +
* Basic familiarity with BRL-CAD command line tools
 +
* Basic familiarity with UNIX
  
−
viewsize 2.500000000e+05;
+
== MEDIUM: Write a "BRL-CAD Ray Tracing Shaders" tutorial ==
−
eye_pt 2.102677960e+05 8.455500000e+04 2.934714650e+04;
 
−
viewrot -6.733560560e-01 6.130643360e-01 4.132114880e-01 0.000000000e+00
 
−
        5.539599410e-01 4.823888300e-02 8.311441420e-01 0.000000000e+00
 
−
        4.896120540e-01 7.885590550e-01 -3.720948210e-01 0.000000000e+00
 
−
        0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00 ;
 
−
start 0;
 
−
end;
 
  
−
Then run rt feeding it that view script as input.  This is an example how to run within the gdb debugger:
+
BRL-CAD includes numerous shaders that let you specify different optical effects during ray tracing.
−
gdb path/to/bin/rt
 
−
...
 
−
(gdb) run -F/dev/X -M .cmake/share/db/star.g all < star.view
 
  
−
At this point, rt should crash due to an infinite recursion.  A backtrace in the debugger will show lots and lots of calls to rt_shootray() and light_hit().
+
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 [http://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf Introduction to MGED] document.
  
−
This task involves investigating and preventing the crash.  Provide a patch that fixes the bug.
+
Time: <4 days
 +
 
 +
Code:
 +
* src/liboptical/sh_*.c (for available shader names and corresponding options)
  
 
References:
 
References:
−
* man gdb
+
* http://brlcad.org/w/images/2/2c/Optical_Shaders.pdf
−
* brlman rt
+
* http://brlcad.org/w/images/c/cf/Introduction_to_MGED.pdf
 +
 
 +
Requirements:
 +
* Basic familiarity with BRL-CAD
 +
* Basic familiarity with word processing software
 +
 
 +
----
  
−
Code:
+
=Translation=
−
* src/librt/shoot.c
+
----
−
* src/liboptical/sh_light.c
+
''Tasks related to localization''
  
−
&nbsp;
+
== VERY EASY: Translate "BRL-CAD Overview" document ==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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
−
| style="padding: 20px;" |
 
−
=== Fix closedb ===
 
  
−
BRL-CAD geometry editor application (mged) has several hundred commands including two very simple commands for opening and closing a geometry database file.  While the user rarely ever needs to close the file, as all changes are always immediately saved, it can be of use to scripting applications.  However, at some point in the recent past, the ''closedb'' command was horked.  It's undoubtedly something very simple but we haven't bothered to look due to other priorities.  You can fix it. If you run these simple steps within graphical mged, you should see how commands stop working after calling closedb:
+
This task involves translating that document into another language correctly while preserving the existing valid Docbook tagging.
  
−
  mged> opendb test.g y
+
Time: <1 day
−
  mged> make sph sph
 
−
  mged> l sph
 
−
  mged> closedb
 
−
  mged> make sph sph
 
−
  mged> opendb test.g
 
−
  mged> l sph
 
−
  mged> exit
 
  
−
Provide a patch that fixes the bug or tell us which SVN revision introduced the bug. Make sure you can reproduce the bug before claiming this task, which presumes you know how to download/install BRL-CAD from a source distribution.
+
References:
 +
* http://brlcad.org/wiki/Overview
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/en/BRL-CAD_Tutorial_Series-VolumeI.xml
  
−
Code:
+
Requirements:
−
* src/mged/mged.c
+
* 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
  
−
&nbsp;
+
== EASY: Translate a chapter from the Introduction to MGED to Portuguese ==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
BRL-CAD has an extensive tutorial series in Docbook XML (very similar to HTML) for our MGED geometry editor.  We already have a complete translation of the document in Spanish and English.  We have a pretty strong Portuguese user base but no documentation in Portuguese.  The Spanish translation may help serve as a translation guide.
−
| style="padding: 20px;" |
 
−
=== Create a utility library (LIBBU) API unit test ===
 
  
−
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 picking one of the 16 chapters, the first available for your preferred language, and translating that chapter.  You'll provide the translated chapter in the same text-based Docbook XML form you start with.
  
−
This task involves implementing new unit tests for any of LIBBU's source files that do not already have a unit test defined.  The test should run all of the public functions and be hooked into our build system.  We have lots of existing unit tests to follow as examples.
+
Time: <1 day
  
 
References:
 
References:
−
* include/bu.h
+
* Introduction to MGED at http://brlcad.org/wiki/Documentation
−
* src/libbu/*.c
+
* doc/docbook
−
* src/libbu/tests/*.c
+
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/en
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/es
  
−
Code:
+
Requirements:
−
* src/libbu/tests/[TEST].c
+
* Proficiency with Portuguese
−
* src/libbu/tests/CMakeLists.txt
+
* Ability to use a text editor
 +
* Basic familiarity with Docbook formatting and word processing
 +
== EASY: Translate a chapter from the Introduction to MGED to Mandarin ==
  
−
&nbsp;
+
BRL-CAD has an extensive tutorial series in Docbook XML (very similar to HTML) for our MGED geometry editor.  We already have a complete translation of the document in Spanish and English.
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
This task involves picking one of the 16 chapters, the first available for your preferred language, and translating that chapter.  You'll provide the translated chapter in the same text-based Docbook XML form you start with.
−
| style="padding: 20px;" |
 
  
−
=== Create Numerics library (LIBBN) API unit tests ===
+
Time: <1 day
  
−
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.
+
References:
 +
* Introduction to MGED at http://brlcad.org/wiki/Documentation
 +
* doc/docbook
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/en
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/es
 +
 
 +
Requirements:
 +
* Proficiency with Mandarin
 +
* Ability to use a text editor
 +
* Basic familiarity with Docbook formatting and word processing
 +
 
 +
== EASY: Translate a chapter from the Introduction to MGED to Hindi ==
  
−
This task involves implementing new unit tests for any of LIBBN's source files that do not already have a unit test defined.  The test should run all of the public functions and be hooked into our build system.  We have lots of existing unit tests to follow as examples.
+
BRL-CAD has an extensive tutorial series in Docbook XML (very similar to HTML) for our MGED geometry editor.  We already have a complete translation of the document in Spanish and English.
  
−
References:
+
This task involves picking one of the 16 chapters, the first available for your preferred language, and translating that chapter. You'll provide the translated chapter in the same text-based Docbook XML form you start with.
−
* include/bn.h
 
−
* include/plot3.h
 
−
* include/vmath.h
 
−
* src/libbn/*.c
 
−
* src/libbn/tests/*.c <-- check this directory for examples
 
−
* src/libbu/tests/*.c <-- Note: Also check this too for more examples.
 
  
−
Code:
+
Time: <1 day
−
* src/libbn/tests/[TEST].c
 
−
* src/libbn/tests/CMakeLists.txt
 
  
−
<b> Note </b>
+
References:
−
A valid task will constitute writing a basic test for each function in the following libbn/ files.
+
* Introduction to MGED at http://brlcad.org/wiki/Documentation
 +
* doc/docbook
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/en
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/es
  
−
&nbsp;
+
Requirements:
 +
* Proficiency with Hindi
 +
* Ability to use a text editor
 +
* Basic familiarity with Docbook formatting and word processing
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: Translate a chapter from the Introduction to MGED ==
−
| style="padding: 20px;" |
 
−
==== ... unit tests for LIBBN anim.c ====
 
−
&nbsp;
 
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 4px;" width="100%"
+
BRL-CAD has an extensive tutorial series in Docbook XML (very similar to HTML) for our MGED geometry editor. We already have a complete translation of the document in Spanish and English.
−
| style="padding: 20px;" |
 
−
==== ... unit tests for LIBBN axis.c ====
 
−
&nbsp;
 
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 4px;" width="100%"
+
This task involves picking one of the 16 chapters, the first available for your preferred language, and translating that chapter.  You'll provide the translated chapter in the same text-based Docbook XML form you start with.
−
| style="padding: 20px;" |
 
−
==== ... unit tests for LIBBN qmath.c ====
 
−
&nbsp;
 
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 4px;" width="100%"
+
Time: <1 day
−
| style="padding: 20px;" |
 
−
==== ... unit tests for LIBBN rand.c ====
 
−
&nbsp;
 
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#efefef; border-style: solid; border-width: 4px;" width="100%"
+
References:
−
| style="padding: 20px;" |
+
* Introduction to MGED at http://brlcad.org/wiki/Documentation
−
==== ... unit tests for LIBBN vector.c ====
+
* doc/docbook
−
&nbsp;
+
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/en
−
|}
+
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/es
−
&nbsp;
 
  
−
&nbsp;
+
Requirements:
−
|}
+
* Proficiency with any language other than English and Spanish
−
&nbsp;
+
* Preferably proficient with Russian, Arabic, Bengali, German, Japanese, or French
 +
* Ability to use a text editor
 +
* Basic familiarity with Docbook formatting and word processing
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: Translate our HACKING developer guide ==
−
| style="padding: 20px;" |
 
  
−
=== Find, reliably reproduce, and report any bug in Archer ===
+
BRL-CAD has an extensive developer guide text file that gives an overview on how to become involved, ways to contribute, practices and conventions to use, and more.
  
−
Archer is our new modeling interface and a soon to merge with our long-standing MGED geometry editor.  It undoubtedly has bugs.  It's your job to find one, 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 specific instructions.  Find a way to make archer crash, become unresponsive, or otherwise behave incorrectly.  You will have to explore the tool with minimal documentation.
+
This task involves faithfully translating our developer guide document into another language.
  
−
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 nor can it be merely behavior you don't like.
+
Time: <1 day
  
 
References:
 
References:
−
* archer
+
* http://brlcad.svn.sourceforge.net/viewvc/brlcad/brlcad/trunk/HACKING
−
* Introduction to MGED at http://brlcad.org/wiki/Documentation (many of the mged commands are available in some fashion within archer)
+
 
−
* BUGS file in any source/binary distribution
+
Requirements:
−
* http://sourceforge.net/tracker/?atid=640802&group_id=105292&func=browse
+
* Proficiency with a second language
 +
* Basic ability to translate technical terms from English to another language
  
−
&nbsp;
+
== MEDIUM: Translate "Principles of Effective Modeling" ==
−
|}
 
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
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).
−
| style="padding: 20px;" |
 
−
=== Reproduce any 10 unconfirmed open bug reports ===
 
  
−
BRL-CAD presently has approximately 75 open bug reports of which 50 are unassigned.  Read the comments and status to see if the bug has been confirmed/reproduced.
+
This task involves taking the existing Docbook XML version of the document and translating the content into another language.
  
−
This task involves going through those reports and REPRODUCE at least 10 of the ones that have not been confirmed.  When you can reproduce the issue being reported, you'll comment on the thread to state as much and attach any data you used to reproduce the crash.
+
Time: <2 days
  
 
References:
 
References:
−
* https://sourceforge.net/tracker/?limit=100&func=&group_id=105292&atid=640802&assignee=100&status=1&submit=Filter
+
* http://brlcad.org/w/images/9/9a/Principles_of_Effective_Modeling.pdf
 +
* https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk/doc/docbook/books/en/BRL-CAD_Tutorial_Series-VolumeIII.xml
  
−
&nbsp;
+
Requirements:
−
|}
+
* Proficiency with a second language
−
&nbsp;
+
* Basic ability to translate technical terms from English to another language
 +
* Basic familiarity with Docbook formatting and word processing
  
−
== 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''
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: Design an MGED command spreadsheet ==
−
| style="padding: 20px;" |
+
 
−
=== Create an ISST screenshot or animation ===
+
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.
  
−
Everyone loves to see screenshots and animations of software in action. We use both in our marketing and outreach. See some of the examples below that we already have.
+
This task involves designing a spreadsheet that will be used to characterize all of MGED's commands.
  
−
Create an awesome screenshot and/or animation of our 'isst' tool in action. It's an interactive geometry viewer interface.  It should be graphically interesting and give some sense of capability.  You should import a visually complex and interesting model with LOTS of polygons and detail.  Note you may have to go through some or the MGED tutorials (see Docs on our website).
+
Time: <2 days
  
 
References:
 
References:
−
* https://brlcad.org/gallery/index.php?/category/12
+
* An existing spreadsheet already being used for BRL-CAD (i.e., non-MGED) commands is available.
  
−
&nbsp;
+
Requirements:
−
|}
+
* Basic ability to use spreadsheet software
−
&nbsp;
+
* Ability to characterize information in a useful tabular form
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== EASY: Create prototype 2D CAD drawing(s) ==
−
| style="padding: 20px;" |
 
  
−
=== Categorize commands into a spreadsheet ===
+
BRL-CAD provides limited services for drafting features including the production of 2D CAD drawings (blueprints).
  
−
BRL-CAD is a suite of more than 400 commands, processing tools, image tools, geometry converters, and more.  MGED also has a command-line with hundreds of commands too.  Help us reorganize one of those command sets.
+
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.
  
−
This task involves creating a spreadsheet that lists all commands and groups them together into a finite set of categories or labels.  This spreadsheet will help us identify places where commands can be consolidated, commands we might want to consider removing, common groupings for documentation, etc. 
+
Time: <3 days
  
−
&nbsp;
+
References:
−
|}
+
* http://brlcad.org/design/drafting
−
&nbsp;
+
* http://en.wikipedia.org/wiki/ISO_128
 +
* http://en.wikipedia.org/wiki/ASME_Y14.41-2003
 +
* http://en.wikipedia.org/wiki/Geometric_Dimensioning_and_Tolerancing
 +
* http://www.ptc.com/WCMS/files/45691/en/4307_FoundationXE_DS.pdf
 +
 +
Requirements:
 +
* Familiarity with CAD drawings
 +
* Ability to recognize important features in CAD drawings
 +
* Familiarity with layout/diagram software
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
== MEDIUM: Create prototype CAD GUI layout diagram ==
−
| style="padding: 20px;" |
 
  
−
=== Design a Cover Photo for Facebook (and other social media) ===
+
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 website and marketing materials are constantly undergoing change.  Effective marketing requires well designed and attractive imagery. Imagery ideally should showcase some feature of BRL-CAD, some highlight, something visually interesting and compelling.
+
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:
 
References:
−
* https://www.facebook.com/brlcad
+
* http://brlcad.org/design/gui
 +
 
 +
Requirements:
 +
* 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.
 +
 
 +
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
  
−
&nbsp;
+
References:
−
|}
+
* Introduction to MGED at http://brlcad.org/wiki/Documentation
−
&nbsp;
 
  
−
{| style="background-color:#fefefe; border-style: solid; border-width: 4px;" width="100%"
+
Requirements:
−
| style="padding: 20px;" |
+
* Basic ability to learn a GUI
−
=== Create a video for BRL-CAD  ===
+
* Basic understanding of usability concepts and ability to organize items logically
  
−
Watching someone else use software is incredibly helpful to some.  Create a screen-cast video for BRL-CAD that showcases some  feature, goes over steps involved in creating some model, or shows how to accomplish some other task.
+
== HARD: Categorize all of BRL-CAD's commands into a spreadsheet ==
  
−
You'll need to install BRL-CAD on your computer and use it in the video.  Create or import some model and make a recording.
+
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.
  
−
&nbsp;
+
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.
−
|}
 
−
&nbsp;
 
  
−
= When You're Done =
+
Time: <4 days
  
−
For non-code, just send us your file(s).  For code changes, you will be expected to [[Patches|provide a patch file]]. Make sure you ''read'' your patch file before submitting it.  Make sure your patch file will apply cleanly to an unmodified checkout of BRL-CAD:
+
References:
 +
* A spreadsheet template will be provided.
  
−
svn co https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk brlcad.edit
+
Requirements:
−
cd brlcad.edit
+
* Basic ability to use spreadsheet software
−
# make changes
+
* Ability to quickly browse files for information
−
svn diff > ~/my.patch
+
* Ability to be methodical and obsessive
−
# read ~/my.patch file with text editor
 
−
cd ..
 
−
svn co https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk brlcad.fresh
 
−
cd brlcad.fresh
 
−
patch -p0 < ~/my.patch
 
−
# submit your patch file to our patches tracker
 
−
&nbsp;
 

Please note that all contributions to BRL-CAD may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see BRL-CAD:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)
Retrieved from "https://brlcad.org/wiki/Deuces"