Commit df2ca560 authored by Dave Cooper's avatar Dave Cooper
Browse files

Started Geometry chapter of manual; fixed datatype bug in X3D Cone output.

parent 69204960
;;
;; Copyright 2002, 2009 Genworks International and Genworks BV
;;
;; This source file is part of the General-purpose Declarative
;; Language project (GDL).
;;
;; This source file contains free software: you can redistribute it
;; and/or modify it under the terms of the GNU Affero General Public
;; License as published by the Free Software Foundation, either
;; version 3 of the License, or (at your option) any later version.
;;
;; This source file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; Affero General Public License for more details.
;;
;; You should have received a copy of the GNU Affero General Public
;; License along with this source file. If not, see
;; <http://www.gnu.org/licenses/>.
;;
The Genworks Bootstrap Utilities
================================
These utilities allow you to compile, incrementally compile, and load
your applications. We give an overview of the expected directory
structure and available control files, followed by a reference for
each of the functions included in the bootstrap module.
1 Directory Structure
=====================
You should structure your applications in a modular fashion, with the
directories containing actual Lisp sources called "source."
You may have subdirectories which themselves contain "source"
directories.
We recommend keeping your codebase directories relatively flat,
however.
Here is an example application directory, with three source files:
apps/yoyodyne/booster-rocket/source/assembly.lisp
apps/yoyodyne/booster-rocket/source/package.lisp
apps/yoyodyne/booster-rocket/source/parameters.lisp
apps/yoyodyne/booster-rocket/source/rules.lisp
2 Source Files within a source/ subdirectory
============================================
2.1 Enforcing ordering
======================
Within a source subdirectory, you may have a file called
"file-ordering.isc" to enforce a certain ordering on the files. Here
is the contents of an example for the above application:
("package" "parameters")
This will force package.lisp to be compiled/loaded first, and
parameters.lisp to be compiled/loaded next. The ordering on the rest
of the files should not matter (although it will default to
lexigraphical ordering).
Now our sample application directory looks like this:
apps/yoyodyne/booster-rocket/source/assembly.lisp
apps/yoyodyne/booster-rocket/source/file-ordering.isc
apps/yoyodyne/booster-rocket/source/package.lisp
apps/yoyodyne/booster-rocket/source/parameters.lisp
apps/yoyodyne/booster-rocket/source/rules.lisp
2.2 Ignoring some source files
==============================
You may specify source files to be ignored with ignore-list.isc. For
example, say our application contains a test-parts.lisp file which
should not be processed as part of a normal build.
You can exclude test-parts.lisp from normal builds by adding a file
called ignore-list.isc at the appropriate level. Here are the contents
of an example ignore-list.isc:
("test-parts")
Now our sample application directory look like this:
apps/yoyodyne/booster-rocket/source/assembly.lisp
apps/yoyodyne/booster-rocket/source/file-ordering.isc
apps/yoyodyne/booster-rocket/source/ignore-list.isc
apps/yoyodyne/booster-rocket/source/package.lisp
apps/yoyodyne/booster-rocket/source/parameters.lisp
apps/yoyodyne/booster-rocket/source/rules.lisp
3 Multiple application modules
==============================
You may have multiple modules within a common parent directory, as per
the following example:
apps/yoyodyne/main-rocket/
apps/yoyodyne/booster-rocket/
apps/yoyodyne/cockpit/
Presumably each of these modules has its own source/ subdirectory, and
probably its own package.lisp and file-ordering.isc file.
3.1 Enforcing ordering
======================
You can enforce ordering on the modules themselves with a
system-ordering.isc file; here are some sample contents of a
system-ordering.isc file:
("main-rocket" "booster-rocket")
Now our sample application directory look like this:
apps/yoyodyne/booster-rocket/
apps/yoyodyne/cockpit/
apps/yoyodyne/main-rocket/
apps/yoyodyne/system-ordering.isc
This will ensure that main-rocket gets processed first, followed by
booster-rocket. The ordering on the rest of the subdirectories should
not matter (although it will default to lexigraphical ordering).
3.2 Ignoring some subdirectories
================================
You may specify subdirectories to be ignored with ignore-list.isc. For
example, say our application contains a test-parts/ directory which
should not be loaded as part of a normal build.
You can exclude test-parts/ from normal builds by adding a file called
ignore-list.isc at the appropriate level. Here are the contents of an
example ignore-list.isc:
("test-parts")
Now our sample application directory look like this:
apps/yoyodyne/booster-rocket/
apps/yoyodyne/cockpit/
apps/yoyodyne/ignore-list.isc
apps/yoyodyne/main-rocket/
apps/yoyodyne/system-ordering.isc
apps/yoyodyne/test-parts/
4 Revision Control
==================
The bootstrap utilities operate on plain files; they do not support
operating directly on revision controlled repository files (e.g. RCS
",v" files).
We recommend using a revision control system such as CVS, with which
the user works with plain files in the home directory as the working
codebase. All builds will then be done from the working files, rather
than directly on the master repository files. The presence of CVS/
subdirectories (or any other subdirectories containing non-lisp files)
will be ignored by the bootstrap utilities.
5 Reference
===========
The utilities are all in the :genworks package. If you want to use
them from another package, do:
(use-package :genworks <other-package>).
Otherwise you can simply prepend "genworks:" to the name of each
function when calling it.
5.1 cl-lite
===========
This is the main function used to compile and load a directory.
(defun cl-lite (pathname &key create-fasl?) "
Traverses pathname in an alphabetical depth-first order, compiling
and loading any lisp files found in source/ subdirectories. A lisp
source file will only be compiled if it is newer than the
corresponding compiled fasl binary file, or if the corresponding
compiled fasl binary file does not exist. A bin/source/ will be
created, as a sibling to each source/ subdirectory, to contain the
compiled fasl files.
If the :create-fasl? keyword argument is specified as non-NIL, a
concatenated fasl file, named after the last directory component of
pathname, will be created in " )
5.2 cl-patch
============
Can be used to patch large systems (e.g. server apps) without forcing
a reload of the entire system.
(defun cl-patch (pathname) "
Traverses pathname in a manner identical to cl-lite, but only those
files for which the source is newer than the corresponding fasl
binary file (or for which the corresponding fasl binary file does
not exist) will be loaded. Use this for incremental updates where
the unmodified source files do not depend on the modified source
files.")
;;
;; Copyright 2002, 2009 Genworks International and Genworks BV
;;
;; This source file is part of the General-purpose Declarative
;; Language project (GDL).
;;
;; This source file contains free software: you can redistribute it
;; and/or modify it under the terms of the GNU Affero General Public
;; License as published by the Free Software Foundation, either
;; version 3 of the License, or (at your option) any later version.
;;
;; This source file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
;; Affero General Public License for more details.
;;
;; You should have received a copy of the GNU Affero General Public
;; License along with this source file. If not, see
;; <http://www.gnu.org/licenses/>.
;;
The GDL Drawing Package User's Manual
=====================================
This file contains basic information and usage instructions for the
Drawing package in the base General-purpose Declarative Language
System.
1.1 Base-drawing
================
Base-drawing is the fundamental object which represents a physical
drawing on a piece of paper. Although the metaphor is a piece of
paper, a drawing can also be displayed in a GWL web application as an
embedded, clickable, zoomable, pannable image. An empty drawing does
not do much of anything. It has to contain at least one object of type
base-view to be useful.
A Drawing is generally output by itself, as one whole unit. GDL
currently does not support outputting of individual parts of a
drawing, or children of a drawing. The Drawing can have as many
children and other descendants as you like. Only those children which
are of type base-view (see 1.2 below) will be included when the
drawing is output.
The main user-controllable :input-slots to a drawing are page-length
and page-width. These are assumed to be in points, where there are 72
points per inch (about 28 points per cm) for purposes of printed
output. The default page size is for US Letter paper, or 8.5 inches
(612 points) for page-width, and 11 inches (792 points) for
page-length. Page-height is essentially the thickness of the page,
which is always zero (0).
1.2 Base-view
=============
1.2.1 Introduction to Base-view
===============================
Base-view represents a flat rectangular section of a drawing, and is a
window onto a set of 3D and/or 2D geometric objects transformed and
scaled in a specified way. The objects can be auto-fit to the page, or
scaled and translated manually with user-specified inputs.
A base-view by itself does not have any defined behavior in GDL. It
must be contained as a child object of a base-drawing.
See the reference documentation for base-view for detailed
explanations of each of the input-slots and other messages. Below is an
overview of the common ones:
1.2.2 the Objects to be Displayed in a Base-view:
============================================================
There are three main input-slots for base-view which specify what
objects are to be included in a view:
objects - a list of GDL objects. These objects will be displayed in
each view by default. Note that these objects are taken
directly -- the children or leaves of these objects are
not displayed (n.b. this is analogous to
ui-display-list-leaves in a base-html-sheet). These
objects are defined in the normal 3D "world" coordinate
system, but will be transformed and scaled according to
the properties of the base-view.
object-roots - a list of GDL objects whose _leaves_ will be
displayed in the view (n.b. this is analogous to
ui-display-list-objects in a base-html-sheet). These
objects are defined in the normal 3D "world"
coordinate system, but will be transformed and scaled
according to the properties of the base-view.
annotation-objects - a list of GDL objects (usually 2D objects such
as dimensioning or text primitives) which you want to
display in the view. These objects are defined in the
coordinate system of the view, and are not scaled or
transformed (so, for example, their size will remain
constant regardless of the scale of the base-view).
1.2.3 the Properties of a Base-View:
=====================================
The common user-specified properties for a base view are:
view-scale - a Number which specifies a factor to convert from model
space to drawing space (in points). If you do not specify
this, it will be computed automatically so as to fit all
objects within the base-view. NOTE that if this is left to be
auto-computed, then you CANNOT normally refer to the
view-scale from within any of the objects or object-roots
passed into the view, as this would cause a circular
reference. If you would like to override this restriction, you
can include the object which refers to the view-scale in the
view's list of immune-objects (documented in the reference
materials).
view-center - a 3D point in the model space which should become the
center of the base-view. If you do not specify this, it will
be computed automatically so as to center all the objects
within the view.
projection-vector - a 3D vector which represents the line of a
camera looking onto the objects in model space.
left-margin - Number which allows the left (and right) margins to be
expanded.
front-margin - Number which allows the front (and rear) margins to be
expanded.
The following examples are taken from
gdl/geom-base/drawing/source/tests.lisp
1.3 Example of a base-drawing with a contained base-view
========================================================
in the Genworks OS code repository. Please see that file for more
complete tests and examples. Note that the robot-assembly is defined
in gdl/gwl/source/robot.lisp in the code repository (and is also
built-in to GDL).
(in-package :gdl-user)
(define-object robot-drawing (base-drawing)
:objects
((main-view :type 'base-view
:projection-vector (getf *standard-views* :trimetric)
:object-roots (list (the robot)))
(robot :type 'gwl-user::robot-assembly)))
You can output this drawing as a PDF file as follows:
(with-format (pdf "/tmp/robot-drawing.pdf") (write-the-object (make-object 'robot-drawing) cad-output))
and as DXF with:
(with-format (pdf "/tmp/robot-drawing.pdf") (write-the-object (make-object 'robot-drawing) cad-output))
and you can probe it in TaTU by instantiating robot-drawing in a TaTU
session, and invoking the Add Node (AN) action on the root object. Be
sure to set the TaTU view to top.
1.4 Example of a base-drawing with some dimensions
==================================================
Note that this example has the main 3D geometry in a separate branch
from the drawing itself:
(in-package :gdl-user)
(define-object box-with-drawing (base-object)
:objects
((drawing :type 'dimensioned-drawing
:objects (list (the box) (the length-dim)))
(length-dim :type 'horizontal-dimension
:start-point (the box (vertex :rear :top :left))
:end-point (the box (vertex :rear :top :right)))
(box :type 'box
:length 10 :width 20 :height 30)))
(define-object dimensioned-drawing (base-drawing)
:input-slots (objects)
:objects
((main-view :type 'base-view
:projection-vector (getf *standard-views* :trimetric)
:objects (the objects))))
You can output this drawing as a PDF file as follows:
(with-format (pdf "/tmp/dimensioned-drawing.pdf")
(write-the-object (make-object 'box-with-drawing) drawing cad-output))
and as DXF with:
(with-format (pdf "/tmp/dimensioned-drawing.pdf")
(write-the-object (make-object 'box-with-drawing) drawing cad-output))
and you can probe it in TaTU by instantiating box-with-drawing in a
TaTU session, and invoking the Add Node (AN) action on the drawing
child object. Be sure to set the TaTU view to top.
1.5 Example of a base-drawing with two views
============================================
Now we give an example of a drawing with two separate views, one
trimetric and one top:
(in-package :gdl-user)
(define-object box-with-two-viewed-drawing (base-object)
:objects
((drawing :type 'two-viewed-drawing
:objects (list (the box) (the length-dim)))
(length-dim :type 'horizontal-dimension
:start-point (the box (vertex :rear :top :left))
:end-point (the box (vertex :rear :top :right)))
(box :type 'box
:length 10 :width 20 :height 30)))
(define-object two-viewed-drawing (base-drawing)
:input-slots (objects)
:objects
((main-view :type 'base-view
:projection-vector (getf *standard-views* :trimetric)
:length (half (the length))
:center (translate (the center) :rear (half (the-child length)))
:objects (the objects))
(top-view :type 'base-view
:projection-vector (getf *standard-views* :top)
:length (half (the length))
:center (translate (the center) :front (half (the-child length)))
:objects (the objects))))
You can output this drawing as a PDF file as follows:
(with-format (pdf "/tmp/two-viewed-drawing.pdf")
(write-the-object (make-object 'two-viewed-drawing) drawing cad-output))
and as DXF with:
(with-format (pdf "/tmp/two-viewed-drawing.pdf")
(write-the-object (make-object 'two-viewed-drawing) drawing cad-output))
and you can probe it in TaTU by instantiating box-with-drawing in a
TaTU session, and invoking the Add Node (AN) action on the drawing
child object. Be sure to set the TaTU view to top.
1.6 Example of a base-drawing with scale-independent annotation-object
======================================================================
Note that in the previous example, the character size on the dimension
changes from view to view, because the view-scale is different in each
view. The following example specifies the dimension as an
annotation-object defined in drawing space, so that it will maintain a
constant character size.
(in-package :gdl-user)
(define-object box-with-annotated-drawing (base-object)
:objects
((drawing :type 'box-annotated-drawing
:objects (list (the box)))
(box :type 'box
:length 10 :width 20 :height 30)))
(define-object box-annotated-drawing (base-drawing)
:input-slots (objects (character-size 15)
(witness-line-gap 10)
(witness-line-length 15)
(witness-line-ext 5))
:objects
((main-view :type 'base-view
:projection-vector (getf *standard-views* :trimetric)
:length (half (the length))
:center (translate (the center) :rear (half (the-child length)))
:objects (the objects)
:annotation-objects (list (the main-length-dim)))
(main-length-dim :type 'vertical-dimension
:pass-down (character-size witness-line-gap witness-line-length witness-line-ext)
:start-point (the main-view (view-point (the box (vertex :rear :top :right))))
:end-point (the main-view (view-point (the box (vertex :rear :bottom :right))))
:dim-value (3d-distance (the box (vertex :rear :top :right))
(the box (vertex :rear :bottom :right)))
:text-above-leader? nil)
(top-view :type 'base-view
:projection-vector (getf *standard-views* :front)
:length (half (the length))
:center (translate (the center) :front (half (the-child length)))
:objects (the objects)
:annotation-objects (list (the top-length-dim)))
(top-length-dim :type 'vertical-dimension
:pass-down (character-size witness-line-gap witness-line-length witness-line-ext)
:start-point (the top-view (view-point (the box (vertex :rear :top :right))))
:dim-scale (/ (the top-view view-scale))
:text-above-leader? nil
:end-point (the top-view (view-point (the box (vertex :rear :bottom :right)))))))
You can output this drawing as a PDF file as follows:
(with-format (pdf "/tmp/box-annotated-drawing.pdf")
(write-the-object (make-object 'box-with-annotated-drawing) drawing cad-output))
and as DXF with:
(with-format (pdf "/tmp/box-annotated-drawing.dxf")
(write-the-object (make-object 'box-with-annotated-drawing) drawing cad-output))
and you can probe it in TaTU by instantiating box-with-drawing in a
TaTU session, and invoking the Add Node (AN) action on the drawing
child object. Be sure to set the TaTU view to top.
1.7 Example of a base-drawing with immune annotation-object
============================================================
The following is not necessary to understand, but might come in useful
occasionally:
Sometimes you may want to specify a dimension in model coordinates,
but have its character-size, witness-line-length, etc. be predictable
in terms of drawing space, regardless of the view-scale. This can be
done by defining the character-size, witness-line-length, etc, as a
factor of the view's view-scale, but in order to do this, the
dimension object must be included in the views list of
immune-objects. Otherwise, a circular reference will result, as the
base-view tries to use the dimension in order to compute the scale,
but the dimension tries to use the scale in order to compute its
sizing.
Here is an example:
(in-package :gdl-user)
(define-object box-with-immune-dimension (base-object)
:objects
((drawing :type 'immune-dimension-drawing
:objects (list (the box)))
(box :type 'box
:length 10 :width 20 :height 30)))
(define-object immune-dimension-drawing (base-drawing)
:input-slots (objects (character-size 20) (witness-line-gap 10)
(witness-line-length 15) (witness-line-ext 5))
:objects
((main-view :type 'base-view
:projection-vector (getf *standard-views* :trimetric)
:objects (append (the objects) (list (the length-dim)))
:immune-objects (list (the length-dim)))
(length-dim :type 'horizontal-dimension
:character-size (/ (the character-size) (the main-view view-scale))
:witness-line-gap (/ (the witness-line-gap) (the main-view view-scale))
:witness-line-length (/ (the witness-line-length) (the main-view view-scale))
:witness-line-ext (/ (the witness-line-ext) (the main-view view-scale))
:start-point (the box (vertex :rear :top :left))
:end-point (the box (vertex :rear :top :right))
)))
You can output this drawing as a PDF file as follows:
(with-format (pdf "/tmp/immune-dimension.pdf")
(write-the-object (make-object 'box-with-immune-dimension) drawing cad-output))