README

NAME

  RGeom: Ruby-driven geometrically-aware mathematical diagram tool


URLS

  Source:    http://github.com/gsinclair/rgeom
  Examples:  http://rgeom.rubyforge.org


DESCRIPTION

  RGeom is a programming language (really a Ruby DSL) for generating
  mathematical diagrams.  It's inspired mainly by Eukleides and Asymptote,
  and also TikZ.

  Eukleides is not powerful enough (need to specify every point, no looping
  constructs) and the others are too low-level for my liking.  They produce
  beautiful vector diagrams in LaTeX documents with a certain degree of
  effort, but I want to produce images for use in Microsoft Word, easily.

  RGeom is targeted at 1.9.2+ and uses Bundler for managing dependencies.


AUDIENCE

  Anyone interested in generating mathematical diagrams easily.  However, see
  'Status' below.

  Ruby is the implementation language.  Users of this software would benefit
  from a little familiarity with Ruby.  The aim is to make the package so
  compelling that people would consider it worthwhile learning a little Ruby
  in order to use it.  That said, this project is designed to scratch my own
  itch.  If nobody else shares that itch, so be it.

  Potential users are encouraged to become familiar with the other software
  packages mentioned above.  They are mature and may meet your needs
  better.


EXAMPLES

  This code would produce a right-angled triangle with a square on each side,
  suitable for demonstrating the Pythagorean Theorem.

    require 'rgeom'

    triangle :ABC, :right_angle => :A, :base => 5, :height => 2.7
    square :base => :BA
    square :base => :CB
    square :base => :AC
    mark_right_angle :CAB

    render 'pythagoras.png'

  Only the 'triangle' and 'render' commands of that code work at the moment,
  but 'square' will be trivially implemented soon.  'mark_right_angle' may
  have to wait a while.

  You can see actual examples of code and the resulting pictures at
  http://rgeom.rubyforge.org.


STATUS

  I'm a high school teacher and can only work on this in my holidays.  At the
  moment (Nov 2009), RGeom can generate triangles (based on many sorts of
  specifications), circles (likewise) and segments.

  Over the Christmas holidays, several features (dots, labels, segment marks,
  angle marks) will hopefully be introduced and a proper release will
  hopefully occur.


FILES AND DIRECTORIES

  etc/
    Scripts for editing code, editing tests, and running tests.
    Aliases that are useful for this project.

  html-demo/
    Example code and descriptions used to create an HTML file
    with lots of pretty pictures and stuff.  Run
      ruby -Ilib html-demo/generate.rb
    to generate the file, and browse html-demo/index.html to
    see the result.

  lib/
    The RGeom library code.

  out/
    A directory into which unit tests can generate images.  These
    may be safely deleted at any time.

  test/
    Unit tests.


USAGE

    require 'rgeom'
    # RGeom code goes here, to define points, segments, triangles, etc.
    render 'filename.png'

  See http://rgeom.rubyforge.org for examples.


DEPENDENCIES

  All dependencies can be installed via Rubygems.

  In RGeom itself:
   * fattr
   * term-ansicolor
   * facets
   * dictionary
   * treetop
   * awesome_print    [debugging code only]
   * ruby-debug       [debugging code only]
   * debuglog         [debugging code only]

  To generate the HTML examples (in addition to the above):
   * rio
   * builder
   * coderay


SEE ALSO

  Eukledies: http://www.eukleides.org

    High-level but not powerful.  This code draw a triangle and its three
    angular bisectors.

      A B C triangle
      draw(A, B, C)
      draw(incircle(A, B, C))
      draw(bisector(B, A, C), dotted)
      draw(bisector(A, B, C), dotted)
      draw(bisector(B, C, A), dotted)

  Asymptote: http://asymptote.sourceforge.net  http://www.piprime.fr/asymptote

    (Extremely) powerful but a bit low-level.  Doesn't strike the right balance
    for high-school mathematical diagrams.  Only for use in TeX.  This example
    draws a triangle and its three medians

      size(2cm,2cm);
      pair A, B, C;
      A=(0,0); B=(1,0); C=(0,1);
      draw(A--B--C--cycle);
      draw (midpoint(A--B) -- C);
      draw (B+0.5*(C-B) -- A);
      draw (interp(A,C,0.5) -- B);
      dot(A/3 + B/3 + C/3);

  TikZ/PGF: http://www.texample.net/tikz

    Same assessment as Asymptote.  The following example draws a circle, the two
    tangents to the circle from a fixed point, and the two corresponding radii.

      \begin{tikzpicture}
        \coordinate (a) at (3,2);
        \node [circle,draw] (c) at (1,1) [minimum size=40pt] {$c$};
        \draw[red] (a) -- (tangent cs:node=c,point={(a)},solution=1)
                  -- (c.center) -- (tangent cs:node=c,point={(a)},solution=2)
                  -- cycle;
      \end{tikzpicture}


AUTHOR AND LICENSE

  Gavin Sinclair
  gsinclair at gmail dot com

  This project uses the MIT License.  See 'LICENSE' for details.