.. _mark_object:
Mark
====
*Mark* objects help the user think about design issues in a way similar to making marks on paper during the sketching or early building design process. They make it easy to visualize and estimate distances. They can be used to establish paths and snap-points (markers) in the design that can be re-used by the user or by other objects.
Each *Mark* object provides a single path and several markers. The number and location of the markers are determined by the length of the gap between them for line marks and the angle for arc and circle marks. The length of gap is a default of *1000 mm* while the angle is *30 degrees*. A marker is created at every interval with a default size (radius) of *25 mm*, shown with circular shapes. These defaults can be changed by the user with the commands ``markerLengthGap``, ``markerSize`` and ``markerAngleGap``. Use the following syntax::
markerLengthGap(200) # set marker length gap to 200 mm
markerLengthGap() # reset gap to default
markerSize(30) # set marker size to 30 mm
markerSize() # reset size to default
markerAngleGap(2) # set marker angle gap to 2 mm
markerAngleGap() # reset shape to use default
.. _mark_snaps:
Markers
-------
The letter "p" is combined with sequential numbers to provide names for the markers. The user can then combine the name of the *Mark* object with an underscore "_" and the name of the marker to access the location of the marker. For example ``mark1_p1`` refers to the location of the first marker for the *Mark* object called "mark1". In addition the user can refer to the path or edge provided by the mark using the symbol ``mark1_p``.
Regardless of the length or how many markers are present, all *Mark* objects have a labeled first, mid and end points. These points can be accessed with ``mark1_b``, ``mark1_m`` and ``mark1_e`` consecutively.
There are three types of *Mark* objects, *lineMark* which defines a linear path, *ArcMark* which defines a curved path and *CircleMark* which defines a circular path.
PointMark
---------
A *PointMark* is the simplest mark object. It is created when the user provides a name only. Buildes creates a single marker for this type of mark which can be accessed by just using the provided name.
The syntax for creating a point mark is `pointMark("mark-name")`. The following is an of a line mark object::
pointMark("pointmark") # PointMark with a single marker
.. _line_mark:
lineMark
----------
A *lineMark* is created when the user provides a name, a length and an angle. Buildes divides the length by the `markLengthGap` setting to determine the position of the markers. If the division is even then the number of markers is equal to the quotient + 1 and all markers are evenly spaced from the beginning to the end of the *lineMark*. If the division is odd, then the number of markers is equal to the quotient + 2. In this case, the markers are spaced evenly except the last two which will have a spacing less than `markLenghtGap` and equal to the remainder. If the length of the line mark is less than the current `markLengthGap` then Buildes simply creates the line mark with three markers that designate the first, mid and end points.
The syntax for creating a line is `lineMark("mark-name", mark-length, mark-angle)`. The following are examples of line mark objects::
# NOTE: First and second line marks are illustrated
# + in Figure: "lineMark illustration"
lineMark("linemark1", 800, 0) # A. lineMark of length 800 mm,
# + inclined at 0 degrees. Using
# + default interval provides 3 markers
lineMark("linemark2", 2500, 90) # B. Provides 4 markers.
lineMark("linemark3") # lineMark of length 1 mm, inclined
# at 0 degrees. Provides 3 markers.
"linemark1_p2" # Refers to the second marker location of linemark1.
"linemark1_p" # Refers to the path or edge provided by linemark1.
"linemark2_m" # Refers to the mid point of linemark2 whether or not a
#+ marker is situated at that location.
"linemark2_b" # Refers to the beginning marker location of linemark2.
"linemark2_e" # Refers to the end marker location of linemark2.
.. note::
"lineMark3" is created with default length and angle. This is appropriate for when it is meant to be placed in the design using "Fit" type of moving which automatically calculates the final parameters (see section on :ref:`put-offset`).
.. comment:
Left this here as an example for commenting.
The following illustration shows "linemark1" and "linemark2". The length of "linemark1" is less than the default `markerLengthGap` so it is marked at the beginning, middle and end points. The second line mark is longer and so is marked from beginning to end by 4 markers at each `markerLengthGap` interval. Note that the length between the last two markers ("p3" and "p4") is less than `markerLengthGap`. The reason is explained above. The actual value of the last interval for marks of this type can be seen by selecting the mark in the tree area of the GUI. In addition, each line mark has labels that can be used to access the first, middle and end points regardless of how many markers it has. This is illustrated with "b", "m" and "e" consecutively.
.. _linemark_illustration:
.. figure:: ills/linemarkObject.png
:align: center
lineMark illustration
ArcMark
-------
A *ArcMark* is created when the user provides a name, a chord length, an angle and an arc height. Buildes divides the arc length by the `markAngleGap` setting to determine the position of the markers. If the division is even then the number of markers is equal to the quotient + 1 and all markers are evenly spaced from the beginning to the end of the *ArcMark*. If the division is odd, then the number of markers is equal to the quotient + 2. In this case, the markers are spaced evenly except the last two which will have a spacing less than `markAngleGap` and equal to the remainder. If the length of *ArcMark* is less than current `markAngleGap` then Buildes simply creates three markers that designate the first, mid and end points on the mark object.
In addition the user can select which side of the chord on which buildes will draw the arc. Imagine standing on the first point of the `arcMark` and looking down the length of the chord. If the arc is on your left (as in :ref:`arcmark_illustration`) then `arcSide` selection is one of *left* or *right* (as in [provide illustration]). The default is the left side. The syntax for creating a arc mark is `arcMark("name-of-arc", "chord-length", angle-of-chord, arc-height, "side-of-arc")`. The following are examples of creating *ArcMark objects*::
# NOTE: First arc mark is illustrated
# + in Figure: "ArcMark illustration".
arcMark("arcmark1", 1200, 90, 200) # ArcMark with chord length 1200 mm,
# + inclined at 90 degrees and arc
# + height of 200 mm.
arcMark("arcmark2", 1200, 90) # ArcMark similar to
# or # + ArcMark1 except arc
arcMark("arcmark2", 1200, 90, arcHeight=0) # + height is 600 forming a
# + perfect semi-circle.
arcMark("arcmark2", 1200, 90, 200, "right") # TODO: ArcMark similar to
# ArcMark1 except the arc
# is created on the right.
arcMark("arcmark3") # ArcMark of chord length 2 mm, inclined at 0
# + degrees and arc height of 1 mm. Provides 3 markers.
The following illustration shows "arcmark1". Using the default `markerAngleGap` value, four markers are created. Similar to the line mark illustration, this arc mark also has a short end interval at "p3" - "p4" and there are labels for accessing the beginning, middle and end points. In addition however, arc marks have a marker at the center of the arc which can be accessed with the label "c".
.. _arcmark_illustration:
.. figure:: ills/arcmarkObject.*
:align: center
ArcMark illustration
CircleMark
----------
A *CircleMark* is created when the user provides a name and a diameter. Buildes divides the circumference by the `markAngleGap` setting to determine the position of the markers. If the division is even then the number of markers is equal to the quotient + 1 and all markers are evenly spaced from the beginning to the end of the *CircleMark*. If the division is odd, then the number of markers is equal to the quotient + 2. In this case, the markers are spaced evenly except the last two which will have a spacing less than `markAngleGap` and equal to the remainder.
The syntax for creating circle mark object is `circleMark("mark-name", mark-diameter)`. The following are examples of creating circle mark objects::
# NOTE: "circlemark1" and "circlemark2" are illustrated
# + in Figure: "CircleMark illustration".
circleMark("circlemark1", 690) # CircleMark with diameter length of 690 mm,
# + CircleMark objects are always inclined at
# + 0 degrees.
markerAngleGap(35) # NOTE: markerAngleGap setting is changed to 35 degrees
circleMark("circlemark2", 690) # CircleMark similar to "circlemark1" but
# + with the change in markerAngleGap, the
# + markers are in different locations.
circleMark("circlemark3") # CircleMark with diameter length of 2 mm.
The following illustration shows "circlemark1" and "circlemark2". Using the default `markerAngleGap` value, twelve markers are created for "circlemark1". When the value of `markerAngleGap` is changed to 35, only eleven markers are created as illustrated. All circle markers are created with a zero degree inclination so the begin, middle and end points are the same. In addition the center point, accessed with "c" is always at the same location as the middle point accessed with "m".
.. _circlemark_illustration:
.. figure:: ills/circlemarkObject.*
:align: center
CircleMark illustration