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)) and as DXF with: (with-format (pdf "/tmp/immune-dimension.dxf") (write-the-object (make-object 'box-with-immune-dimension) 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. 2 Base-drawing and base-view included in Web applications ========================================================= A base-drawing can be included in a web application by giving it as the only item in the list of :objects in the view-object of a base-html-graphics-sheet. Only one drawing may be shown in a single base-html-graphics-sheet. A base-view alone _may not_ be specified as an :object in the view-object of a a base-html-graphics-sheet. Any base-views must be contained in a parent base-drawing. This will be covered in more detail in the revised GWL tutorial.