Difference between revisions of "Deuces"

From BRL-CAD
m (Fix Image Formatting in BRL-CAD's DocBook Documentation (any ONE large document or 4 smaller documents))
(Documentation and Training: Add task for COM-GEOM model transcription from PDF scan of report)
Line 564: Line 564:
  
 
|}
 
|}
 +
 +
 +
 
 +
{| style="background-color:#ffffff;" cellpadding="20" cellspacing="0" border="2" width="100%"
 +
|
 +
=== Transcribe a COM-GEOM Geometry Model from a PDF report to an ASCII file ===
 +
 +
We have scans of a number of reports documenting early geometric models from the analysis system that preceeded BRL-CAD.  These reports often contain the actual geometry defining the model as pages and pages of numbers, but the quality is sufficiently poor that optical character recognition is not reliable.
 +
 +
This task is to attempt the manual transcription of the MEP-021A Generator Set model described in the report "A Combinatorial Geometry Computer Description of the MEP-021A Generator Set" (see the References list below for the link that will let you download the PDF).  One possible approach is to use Acrobat Reader or some other PDF reader select and copy the OCR text, paste that to a text file as a starting point, and then manually correct it.  There may also be some patterns that will allow for semi-automated processing (for example, if 5 zeros in a row are commonly replaced with the character "O" instead of 0, a search and replace is in order.)  However you wish to approach it is fine, but remember that the goal is not just the extraction of the OCR text but the production of an accurate transcription of the file.  The OCR text can be used as a starting point but is not likely to be accurate.
 +
 +
At the end of the day, the goal is to have a file that can be fed to BRL-CAD's comgeom-g importer to generate an accurate .g file.  If the generator conversion goes well, there are a significant number of other models (some of them considerably more complex) that we are interested in that can be used to create more tasks of this nature.
 +
 +
References:
 +
* http://www.dtic.mil/docs/citations/ADA073408
 +
 +
Code:
 +
* src/conv/comgeom
 +
 +
|}
 +
  
 
----
 
----

Revision as of 09:01, 15 November 2013

This is a list of succinct tasks that are expected to take most people familiar with the prerequisites less than two hours to complete. It's a great starting point for anyone interested in contributing to BRL-CAD.

The tasks are all roughly the same complexity with no prior BRL-CAD experience expected. A description is provided along with a list of references and files you'll probably need to edit. Can we make it any easier?

Getting Started

Contact us (via IRC or brlcad-devel mailing list) if you have questions, comments, or ideas of your own you'd like to suggest.

We've made an awesome virtual disk image that has everything you need preconfigured and ready to go:

  1. Download our BRL-CAD Virtual Machine (VM) disk image.
  2. Install VirtualBox.
  3. Import and start the VM, log in (the password is "Brlcad!" without the quotes).
  4. Run "svn up brlcad.svn" and get started!

Pick a Task

We break down all tasks into one of five categories. Don't be worried if the tasks all sound confusing to you. Just pick one and start reading the references we've provided. Join IRC or our mailing list and ask questions.

  1. Code (programming)
  2. Documentation and Training (writing)
  3. Outreach and Research (graphics)
  4. Quality Assurance (testing)
  5. User Interface (designing)

Contents


Code


Tasks related to writing or refactoring code

See the When You're Done section above for details on submitting your changes.

 

Fix bounding box function for our polygonal mesh (BoT) primitive

BRL-CAD provides functions for its geometric primitives that define a bounding box - a box that completely encloses the volume described by the primitive. Ideally, these boxes are as small as possible while still enclosing the primitive. Currently the routine for BoTs is incorrect. You can use stl-g, obj-g, or any of our other *-g converters to import BoT geometry for testing.

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

Code:

  • src/librt/primitives/bot/bot.c

   

Close MGED 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 command window and an interactive graphics window. When the user closes one of those windows, there is a bug. Closing the graphics window closes the command window.

This task involves fixing this behavior so that ONLY closing both windows terminates the process properly and that closing either window does not take the other along with it.

Code:

  • src/mged/mged.c
  • src/tclscripts/mged/openw.c

 

Add MGED key-binding to reopen the command window

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, it creates 2 windows: a text-console command window and an interactive graphics window. If the user closes the text-console command window, they are left with the interactive graphics window. There is presently no way (correct us if we're wrong) to get the text-console back without restarting mged. A good way to test this is to run in classic mode and run the 'gui' command:

sushi:~ morrison$ mged -c test.g
BRL-CAD Release 7.22.0  Geometry Editor (MGED)
    Fri, 24 Aug 2012 00:02:42 -0400, Compilation 6
    morrison@sushi.local:/usr/brlcad/rel-7.22.0

attach (nu|X|ogl)[nu]?   
mged> gui

This task involves adding some mechanism, perhaps a simple key binding, to the graphics window so that you can get the command window back on-demand.

Code:

  • src/mged/mged.c
  • src/tclscripts/mged/openw.c

 

Implement a primitive surface area function

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

This task involves writing a new callback function that takes an rt_db_internal object and calculates the surface area (units are mm^2). There are numerous examples in our code where we compute surface area for other primitives. The primitives that do not already have a centroid callback are itemized in following.

References:

 

... surface area function for elliptical hyperboloids (EHY)

Code:

  • src/librt/primitives/ehy/ehy.c

 

... surface area function for hyperboloids of one sheet (HYP)

Code:

  • src/librt/primitives/hyp/hyp.c

 

... surface area function for N-faced polysolid (ARBN)

Code:

  • src/librt/primitives/arbn/arbn.c

 

... surface area function for extruded bitmaps (EBM)

Code:

  • src/librt/primitives/ebm/ebm.c

 

... surface area function for gridded volumes (VOL)

Code:

  • src/librt/primitives/vol/vol.c

 

... surface area function for super ellipsoids (SUPERELL)

Code:

  • src/librt/primitives/superell/superell.c

 

... surface area function for polygonal meshes (NMG)

Code:

  • src/librt/primitives/nmg/nmg.c

 

... surface area function for NURBS objects (BREP)

Code:

  • src/librt/primitives/brep/brep.cpp

 

Implement a primitive volume function

BRL-CAD provides more than two dozen types of geometry "primitives" such as ellipsoids, boxes, and cones. Every primitive is described by a collection of callback functions, for example rt_ell_bbox() returns the bounding box dimensions for an ellipsoid. Wikipedia, Wolfram Mathworld, and various other math sites (and research papers) around the web include the equations for most of our basic primitives while others are a little more difficult 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). There are numerous examples in our code where we compute volume for other primitives. The primitives that do not already have a volume callback are itemized in following.

References:

... volume function for elliptical hyperboloids (EHY)

Code:

  • src/librt/primitives/ehy/ehy.c

 

... volume function for superellipsoids (SUPERELL)

Code:

  • src/librt/primitives/superell/superell.c

 

... volume function for extruded bitmaps (EBM)

Code:

  • src/librt/primitives/ebm/ebm.c

 

... volume function for triangle meshes (BOT)

Code:

  • src/librt/primitives/bot/bot.c

 

... volume function for solid polygonal meshes (NMG)

Code:

  • src/librt/primitives/nmg/nmg.c

 

... volume function for extruded sketches (EXTRUDE)

Code:

  • src/librt/primitives/extrude/extrude.c

 

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 while others are a little more tricky to compute.

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 primtiives. The primitives that do not already have a centroid callback are itemized in following.

References:

Code:

  • src/librt/primitives/table.c
  • src/librt/primitives/[PRIMITIVE]/[PRIMITIVE].c


... centroid function for right hyperbolic cylinders (RHC)

 

... centroid function for gridded volumes (VOL)

 

... centroid function for N-faced polysolids (ARBN)

 

... centroid function for extruded sketches (EXTRUDE)

 

... centroid function for superellipsoids (SUPERELL)

 

... centroid function for solid polygonal meshes (NMG)

 

 

Implement a primitive UV-mapping callback

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

This task involves implementing a UV-mapping callback for any of the primitives that do not already have a functional UV-callback defined. 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.

References:

... UV-mapping for extruded sketches (EXTRUDE)

Code:

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

 

 


Documentation and Training


Tasks related to creating/editing documents and helping others learn more about BRL-CAD

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:

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.

Code:

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

 

Document MGED's 'saveview' command options

BRL-CAD's primary geometry editor (MGED) provides hundreds of commands. Two of those commands are the savewview and loadview commands that write current view settings out to a text file and read them back in. The saveview command provides -e -i -l and -o options, but they are not documented.

This task involves writing documentation for those missing options. Consult the source code to see what they do and add the corresponding sections into our Docbook XML doc just like we do in our other documentation files. Test compilation to make sure your XML syntax is correct.

References:

  • src/libged/saveview.c
  • doc/docbook/system/mann/en/*.xml

Code:

  • doc/docbook/system/mann/en/saveview.xml

 

Write a "BRL-CAD Commands Quick Reference" document

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

This task involves writing a quick reference document similar to the MGED quick reference but for BRL-CAD commands. The sheet should minimally include the following commands:

mged, rt*, *-g, g-*, fb*, *fb, nirt, remrt, rtsrv, asc2g, g2asc, dbupgrade, pix*, *pix, *-*, brlman, benchmark

References:

 

Doxygen cleanup

BRL-CAD uses Doxygen for most API documentation but the comment blocks are not optimally set up for Doxygen output.

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.

References:

... doxygen cleanup for LIBBU

There are approximately 300 documented API function calls in LIBBU.

Code:

  • include/bu.h
  • src/libbu
  • misc/Doxyfile

 

... doxygen cleanup for LIBWDB

There are approximately 100 documented API function calls in LIBWDB.

Code:

  • include/wdb.h
  • include/raytrace.h
  • src/libwdb
  • misc/Doxyfile

 

... doxygen cleanup for LIBRT

There are approximately 1000 documented API function calls in LIBRT.

Code:

  • include/raytrace.h
  • src/librt
  • src/librt/primitives
  • src/librt/comb
  • src/librt/binunif
  • misc/Doxyfile

 

Write a manual page for MGED's "brep" command

BRL-CAD's MGED geometry editor provides hundreds of commands. One of those commands for manipulating and visualizing geometry is the "brep" command.

This task involves writing a manual page for that command in the Docbook XML format. There are lots of examples to follow.

References:

  • doc/docbook/system/mann/en/*.xml
  • http://brlcad.org/wiki/Documentation (contains intro to mged and cheat sheets)
  • bin/mged (you'll need to run this to use the "brep" command)
  • bin/csgbrep (will create a slew of 'brep'/nurbs objects for the "brep" command)

Code:

  • doc/docbook/system/mann/en/brep.xml (you write this)
  • doc/docbook/system/mann/en/CMakeLists.txt (you edit this)

Running "make" in a build directory will compile your documentation into html and man page format so you can validate the syntax and formatting. See Compiling for help.

 

Write up Wiki page tutorial on our Volumetric Primitive

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.

This task involves writing up a page on the VOL primitive. Figure out how to use it (see the "in" command), create an example input data set, and write up a wiki page on exactly what steps are needed similar to our other wiki pages:

References:

Show how to create a VOL with at least two layers/slices. Include images like the other examples. Put the write-up at http://brlcad.org/wiki/VOL

 

Write a wiki tutorial on how to create a polygonal mesh (NMG) manually

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.

This task involves writing up a page on the NMG polygonal mesh primitive. Figure out how to use it (not a simple task, will require some trial and error), create an example input, and write up a wiki page on exactly what steps are needed similar to our other wiki pages:

References:

Note the "facetize" command in mged will convert an existing object into NMG format. The get/put commands should help from there like the sketch tutorial.

Show how to create an NMG cube or wedge or similar simple shape. Include images like the other examples. Put the write-up at http://brlcad.org/wiki/NMG

 

Fix Image Formatting in BRL-CAD's DocBook Documentation (any ONE large document or 4 smaller documents)

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.

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:

 <mediaobject>
   <imageobject>
     <imagedata align="center" fileref="../../lessons/en/images/img.png" format="PNG"/>
   </imageobject>
   <caption>
     <para>
       Caption goes here.
     </para>
   
 </mediaobject>

This task involves switching image inclusions that use the above style to something like the following:

 <mediaobject>
   <imageobject role="html">
     <imagedata align="center" fileref="../../books/en/images/img.png" format="PNG"/>
   </imageobject>
   <imageobject role="fo">
     <imagedata align="center" fileref="../../books/en/images/img.png" format="PNG"/>
   </imageobject>
   <caption>
     <para>
       Caption goes here.
     </para>
   
</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.

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.

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.

References:

  • doc/docbook/books/en/BRL-CAD_Tutorial_Series-VolumeIII.xml

Code:

  • doc/docbook


 

Transcribe a COM-GEOM Geometry Model from a PDF report to an ASCII file

We have scans of a number of reports documenting early geometric models from the analysis system that preceeded BRL-CAD. These reports often contain the actual geometry defining the model as pages and pages of numbers, but the quality is sufficiently poor that optical character recognition is not reliable.

This task is to attempt the manual transcription of the MEP-021A Generator Set model described in the report "A Combinatorial Geometry Computer Description of the MEP-021A Generator Set" (see the References list below for the link that will let you download the PDF). One possible approach is to use Acrobat Reader or some other PDF reader select and copy the OCR text, paste that to a text file as a starting point, and then manually correct it. There may also be some patterns that will allow for semi-automated processing (for example, if 5 zeros in a row are commonly replaced with the character "O" instead of 0, a search and replace is in order.) However you wish to approach it is fine, but remember that the goal is not just the extraction of the OCR text but the production of an accurate transcription of the file. The OCR text can be used as a starting point but is not likely to be accurate.

At the end of the day, the goal is to have a file that can be fed to BRL-CAD's comgeom-g importer to generate an accurate .g file. If the generator conversion goes well, there are a significant number of other models (some of them considerably more complex) that we are interested in that can be used to create more tasks of this nature.

References:

Code:

  • src/conv/comgeom



Outreach and Research


Tasks related to community management, outreach/marketing, studying problems, and recommending solutions

 

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

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

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

Code:

  • src/conv/iges

 

Write article on BRL-CAD's code hardening efforts

We've been working for several years on "code hardening", improving the quality of BRL-CAD's source code through a variety of best practices and code cleanup efforts.

This task has you write an article that succinctly summarizes all of our efforts. You'll need to become familiar with our HACKING file as well as read up on our various hardening efforts. You're welcome to ask our devs questions over IRC for more information too.

Include at least one picture. Article should be 300-900 words long and be fully proof-read before submitting (check for grammar and spelling mistakes, please).

Resources:

Add the article to http://brlcad.org/wiki/Community_Publication_Portal


 

Write an article soliciting a Windows platform maintainer

BRL-CAD runs on a number of platforms and distributes releases many times a year. Creating a release for any particular binary platform, like Windows or Mac OS X or Linux, is delegated to a "release maintainer". We currently have maintainers for a number of platforms but do not have one for Windows. Basically, it's a volunteer job, it's a lot of work, but not very hard and very rewarding. There are thousands of binary downloads every month, so lots of people benefit from a maintainer's efforts.

This task involves writing a brief solicitation article announcing our interest for a maintainer, describing the responsibilities involved, and telling them how to take up this responsibility. Come talk to us on IRC for more specific details.

Resources:

(See the release section near the bottom to see what maintainers do)

Add the article to http://brlcad.org/wiki/Community_Publication_Portal

 

Create an ISST screenshot or animation

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.

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.

References:

Note that we have several screenshot tasks. Note you may have to go through some or our basic MGED tutorials (see docs section on our website) just to be able to display geometry. Finally, give others a chance if you already completed one of the other screenshot tasks. ;)

 

Generate a code coverage report (lcov+gcov)

This task involves setting up and generating an lcov code coverage analysis on BRL-CAD. After learning how to use the tool, discuss with the developers what portion of the code will be most useful to analyze, or scan these:

"benchmark" "make test" "make regress" Submit the results.

 

Model BRL-CAD logo in BRL-CAD

The BRL-CAD Logo depicts two interlocked nodes. Modeling the new Logo in BRL-CAD in CSG (without NURBS, without polygons) requires some careful arrangement, but can provide an attractive three dimensional rendering that we can use for a number of purposes..

The output of this task will be a .g file of BRL-CAD logo and a rendered image. The two segments you model MUST be two or more regions, ideally hinged together (you can have center pins or not, you decide). This is your opportunity as an artist and 3D magician to come up with an interesting yet faithful interpretation.

References:

Note that there are other logo modeling tasks and yours must start from scratch and be completely original. If we get a hint that yours was based off of or used measurements from some other model, you will be barred.

 

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

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.

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.

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

Running "tops" within mged will tell you what geometry is available for rendering.

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.

 

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!):

http://www.google-melange.com/gci/task/view/google/gci2012/7946218

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.

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.

 

Create prototype 2D Drawing

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

This task involves designing a 2D CAD drawing prototype. The prototype MUST capture a set of design requirements and follows industry conventions.

If you've never seen a real blueprint drawing before, then this task might be too hard for you. Your result needs to refer to ISO 128 and/or ASME Y14.41 or other standard drawing elements.

Basically, identifying a style of drawing that we should support including pointing out the critical elements to be included on each drawing, their location, size, placement, etc.

References:

Note that this is a "redo" of a previous GCI task. Read the discussion thread and his work to help ensure you don't make similar mistakes. ;-)

http://www.google-melange.com/gci/task/view/google/gci2012/7985229



Quality Assurance


Tasks related to testing and ensuring code is of high quality

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.

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:

viewsize 2.500000000e+05;
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:

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 investigating and preventing the crash. Provide a patch that fixes the bug.

References:

  • man gdb
  • brlman rt

Code:

  • src/librt/shoot.c
  • src/liboptical/sh_light.c

 

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:

 mged> opendb test.g y
 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.

Code:

  • src/mged/mged.c

 

Create an 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 implementing a new unit test 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 an example.

References:

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

Code:

  • src/libbu/tests/[TEST].c
  • src/libbu/tests/CMakeLists.txt

... unit test for LIBBU badmagic.c

 

... unit test for LIBBU bomb.c

 

Create numerics library (LIBBN) API unit test

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

This task involves implementing a new unit test 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 an example.

References:

  • include/bn.h
  • include/plot3.h
  • include/vmath.h
  • src/libbn/*.c
  • src/libbu/tests/*.c <-- note libbu, not libbn for examples

Code:

  • src/libbn/tests/[TEST].c
  • src/libbn/tests/CMakeLists.txt

... unit test for LIBBN axis.c

 

... unit test for LIBBN qmath.c

 

... unit test for LIBBN rand.c

 

Find, reliably reproduce, and report any bug in Archer

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

References:

 

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

References:


User Interface


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

 

Design a prototype CAD GUI layout

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

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

References:

Provide one or more mock-up images (png, pdf, psd, html, whatever)

Search for other similar GCI tasks to avoid making a similar design. You can use any tools, but your work must be original.

 

Create an ISST screenshot or animation

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.

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.

References:

Note that we have several screenshot tasks. Note you may have to go through some or our basic MGED tutorials (see docs section on our website) just to be able to display geometry. Finally, give others a chance if you already completed one of the other screenshot tasks. ;)

 

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

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

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

References:

  • A spreadsheet template will be provided.

 

Redesign MGED/Archer's Menu

BRL-CAD's geometry editing applications, like most graphical applications, have an application menu with a variety of features, capabilities, and options, but with little attention to cohesive design.

Review the menus for MGED and Archer. Design a new menu system based on both of them that eliminates confusion, is easier to navigate, and has menu options more logically grouped together.

References:

  • mged
  • archer

Provide screenshots or detailed text indicating what menu options should be available and what exactly is on each menu.

 

Create Wordpress theme for BRL-CAD website

BRL-CAD's website was recently redesigned. The current website uses Drupal and Mediawiki. Our new website will be using Wordpress and Mediawiki.

This task involves creating a custom Wordpress theme based on our new website design.

References:

 

Migrate Drupal site to Wordpress

BRL-CAD's main website content runs on Drupal. There are a lot of articles, user accounts, and other information contained within this installation of Drupal.

This task involves setting up an installation of Wordpress on our production server and migrating the data from Drupal into the Wordpress site.

References:

This task requires that you establish an account on one of our servers. There is a setup process involved. Join us on IRC for details.


When You're Done


For non-code, just send us your file(s). For code changes, you will be expected to 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:

svn co https://brlcad.svn.sourceforge.net/svnroot/brlcad/brlcad/trunk brlcad.edit
cd brlcad.edit
# make changes
svn diff > ~/my.patch
# 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