solvespace/doc/reference.txt

This is a reference manual for SolveSpace. This document is not intended
for new users; to learn about this program, see the video tutorials.

<h2>General Navigation</h2>

    The user interface consists of two windows: a larger window that
    contains mostly graphics, and a smaller window that contains mostly
    text. The graphics window is used to draw the geometry, and to view
    the 3d model. The text window provides information about the model,
    and may also be used to modify settings and numerical parameters.

    <h3>Graphics Window and Model View</h3>

        To pan the view, right-drag with the mouse.

        To rotate the view, center-drag with the mouse. This turns the
        part over, so that the surfaces that used to be hidden (because
        they were facing backwards, away from the viewer) become visible.

        To rotate the view within the plane of the monitor,
        Ctrl+center-drag with the mouse.

        It is also possible to pan by Shift+center-dragging, or to rotate
        by Shift+right-dragging.

        To zoom in or out, rotate the scroll wheel. It is also possible
        to zoom by using the View menu, or the associated keyboard
        shortcuts (+ and -). Some features, including the planes, are
        always drawn the same size on-screen, and are therefore not
        affected by zooming.

        To zoom to the extent of the part, choose View -> Zoom To
        Fit. This adjusts the zoom level so that the part fits exactly
        on the screen, and then pans to center the part. The rotation
        of the part is not affected.

        If a workplane is active, then choose Sketch -> In Workplane (or
        press W) to align the view to the workplane. After doing this,
        the plane of the screen is coincident with the workplane, and
        the center of the workplane is at the center of the screen. The
        zoom level is not affected.

        The x, y, and z coordinate axes are always drawn at the bottom
        left of the graphics window, in red, green, and blue. These axes
        are live: they can be highlighted and selected with the mouse, in
        the same way as any other normals. (This means that the coordinate
        axes are always conveniently available on-screen, which is useful
        e.g. when constraining a line parallel to the x-axis.)

    <h3>Dimension Entry and Units</h3>

        Dimensions may be displayed in either millimeters or inches.
        Millimeter dimensions are always displayed with two digits
        after the decimal point (45.23), and inch dimensions are always
        displayed with three (1.781).

        Choose View -> Dimensions in Inches/Mm to change the current
        display units. This does not change the model; if the user
        changes from inches to millimeters, then a dimension that was
        entered as 1.0 is now displayed as 25.40.

        All dimensions are entered in the current display units. In most
        places where a dimension is expected, it's possible to enter an
        arithmetic expression ("4*20 + 7") instead of a single number.

    <h3>Text Window</h3>

        The text window appears as a floating palette window. It may
        be shown or hidden by pressing Tab, or by choosing View ->
        Show Text Window.

        The text window works like a web browser. Any underlined text is
        a link. To activate a link, click it with the mouse. The links
        may be used to navigate to other pages in the text window. For
        example, the "home" screen is a list of groups in the sketch:

        <img src="/pics/ref-text-window.png" />

        To navigate to a group's page, click on that group's name (e.g.,
        "g002-sketch-in-plane"). The links may also trigger actions in
        the sketch. For example, in the above screenshot, all of the
        groups are shown. To hide a group, click on the word "yes" in the
        "show" column.

        As a convenience, the text window will sometimes automatically
        navigate to a page that is likely to be relevant. For example,
        when a new group is created, the text window displays that new
        group's page. It's always possible to navigate to a different
        page, by clicking the "home" link at the top left corner (or
        pressing Esc), and following the links from there.

        When sketch entities are selected (e.g., the user has clicked
        on them with the mouse), information about those entities is
        displayed in the text window. If a single entity is selected,
        then information about that entity is displayed. For example,
        the window display's a circle's center and radius.

        If multiple entities are selected, then the text window can
        sometimes display information about all of them. These cases
        include:

            two points: the distance between the points

            a point and a plane face: the distance from the point to the
            plane

            two points, and a vector: the distance between the points,
            projected along the vector

            two plane faces: the angle between the plane faces


    <h3>Show / Hide Entities</h3>

        As the sketch becomes more complex, it may be useful to hide
        unnecessary information. SolveSpace provides several different
        ways to do this.

        In the second and third line of the text window, links are
        provided to hide and show different things. These are:

               wrkpls  -- When a new "Sketch In New Workplane" group is
                          created, an associated workplane is created
                          automatically. If wrkpls is hidden, then that
                          workplane is visible only when its associated
                          group is active. If wrkpls is shown, then the
                          workplane is always visible.

               normals -- By default, normals are drawn as blue-grey arrows,
                          in the direction of the normal. These normals may
                          be hovered and selected with the mouse, for
                          example in order to constrain them. This link
                          may be used to hide them.

               points  -- By default, points are drawn as green squares.
                          These points may be hovered and selected with the
                          mouse, for example in order to constrain them.
                          This link may be used to hide them. If points are
                          hidden, then they will still appear when the mouse
                          hovers over them, and may still be selected.

            constraints - When a constraint is created, a graphical
                          representation of that constraint is displayed
                          in purple. The constraints in a group are
                          visible only when that group is active. To hide
                          them even then, use this link.

               shaded --  The 3d part is displayed as an opaque solid,
                          with lighting effects to give the impression of
                          depth. This link may be used to hide that
                          view.

               faces  --  Some surfaces on the 3d model may be selected.
                          For example, the user can select a plane face
                          of the part, and constrain a point to lie on
                          that plane. If faces are shown, then the faces
                          will appear highlighted when the mouse hovers
                          over them. The user can click the mouse to
                          select the face, as they would for any other
                          entity.

                          As a convenience, faces are automatically
                          hidden when a new sketch group is created,
                          and automatically shown when a new extrusion is
                          created. If this behavior is not what's desired,
                          then the faces can be shown or hidden manually
                          with this link.

                 mesh --  The 3d model of the part consists of many
                          triangles; for example, a rectangular face is
                          represented by two triangles. Use this link to
                          show the triangles on the model. This is a good
                          way to see how fine or coarse the mesh is
                          before exporting it.

           hidden-lines - With the part in a given orientation, some of
                          the lines in the part will be invisible,
                          because they are buried inside the solid part.
                          To show those lines anyways, as if the part
                          were transparent, use this link. This is useful
                          when drawing a sketch that lies within the
                          volume of the part.

        In addition to the above options, it is possible to hide and show
        entire groups. If a group is hidden, then all of the entities
        (line segments, circles, arcs, points, etc.) from that group
        are hidden. The solid model is not affected; if a hidden group
        contains a circle that is extruded to form a cylinder, then the
        cylinder will remain visible.

        To hide a group, go to the home screen in the text window, by
        pressing Esc or choosing the link at the top left. A list of
        groups is displayed, along with their visibility. If a group is
        visible, then the "show" column contains the word "yes" in green.
        Click the "yes"; it now appears as a greyed "no", and the group
        is hidden.

        The show / hide status of groups is saved in the part file. If
        a part is imported into an assembly, then entities that were
        visible in the part file will be visible in the assembly, and
        entities that were hidden will be hidden.

    <h3>Active Workplane</h3>

        SolveSpace represents all geometry in 3d; it's possible to draw
        line segments anywhere, not just in some plane.

        This freedom is not always useful, so SolveSpace also makes
        it possible to draw in a plane. If a workplane is active, then
        all entities that are drawn will be forced to lie that plane.
        The active workplane ("wrkpl") is indicated in the top line of
        the text window, at the right.

        When SolveSpace starts with a new empty file, a workplane parallel
        to the XY plane is active. To deactivate the workplane, and draw
        in 3d, choose Sketch -> Anywhere In 3d.

        To activate a workplane, select it, and then choose Sketch ->
        In Workplane. When a workplane is activated, the view is aligned
        onto that workplane. (The workplane remains active until the
        user chooses Sketch -> Anywhere In 3d, or a different workplane
        is activated. If the user rotates the view, so that the view
        is no longer aligned onto the workplane, then the workplane
        remains active.)

        In a "Sketch in New Workplane" group, the group's associated
        workplane may be activated by choosing Sketch -> In Workplane;
        there is no need to select it first.

    <h3>Active Group</h3>

        When a new line, circle, or other curve is created, it will be
        created in the active group.

        Geometry from the active group is drawn in white; geometry from
        earlier groups is drawn in brown. Later groups are hidden.

        In the text window's home screen (press Escape, or choose the
        link in the top left corner), the active group's line in the
        list of groups has "yes" in the "actv" column. All other groups
        (except g001-#references, which cannot be activated) have "no"
        in that column. To activate an inactive group, click on the "no".


<h2>Sketch Entities</h2>

    <h3>Construction Geometry</h3>

        In normal operation, the user draws line and curves in a
        sketch. Those curves describe the geometry to be manufactured;
        ultimately, the endmill or the laser or some other tool will
        cut along those curves.

        In some cases, it is useful to draw a line that should not
        appear on the final part. For example, the user may wish to draw
        a center line for a symmetric part; but that center line is only
        a guide, and should not actually get exported with the CAM data.
        These lines are called construction lines.

        To mark an entity as construction-only, choose Sketch -> Toggle
        Construction. A construction entity will behave just like any
        other entity, except that it is drawn in green, and does not
        contribute to the geometry for export (or to the section that
        will be extruded or lathed or swept).

    <h3>Datum Point</h3>

        This entity is defined by a single point.

        If a workplane is active when the datum point is created,
        then that datum point will always lie in the workplane. If no
        workplane is active, then the datum point will be free in 3d.
        (This is the same behaviour as for all points, including e.g. the
        endpoints of a line segment.)

        Datum points are typically used as construction geometry. The user
        might place datum points in order to simplify the dimensioning
        of line segments or other entities.

    <h3>Workplane</h3>

        This entity is specified by a point and a normal. The point
        defines its origin, and the normal defines its orientation.

        A workplane makes it possible to draw a section in 2d. If a
        workplane is active, then any entities that are drawn must lie
        in that workplane.

        It's almost never necessary to create workplanes explicitly.
        Instead, create a new Sketch in New Workplane group.

    <h3>Line Segment</h3>

        This entity is specified by its two endpoints. If a workplane is
        active, then the two endpoints will always lie in that workplane.

        To create the line segment, choose Sketch -> Line Segment, and
        then left-click one endpoint of the line. Then release the mouse
        button; the other endpoint is now being dragged.

        To create another line segment, that shares an endpoint with
        the line segment that was just created, left-click again. This
        is a fast way to draw closed polygons.

        To stop drawing line segments, press Escape, or right- or
        center-click the mouse. SolveSpace will also stop drawing new
        line segments if an automatic constraint is inserted. (For
        example, draw a closed polygon by left-clicking repeatedly, and
        then hovering over the starting point before left-clicking the
        last time. The endpoint of the polyline will be constrained to
        lie on the starting point, and since a constraint was inserted,
        SolveSpace will stop drawing.)

    <h3>Rectangle</h3>

        This entity consists of two vertical line segments, and two
        horizontal line segments, arranged to form a closed curve.
        Initially, the rectangle is specified with the mouse by two
        diagonally opposite corners. The line segments (and points)
        in the rectangle may be constrained in the same way as ordinary
        line segments.

        It would be possible to draw the same figure by hand, by drawing
        four line segments and inserting the appropriate constraints. The
        rectangle command is a faster way to draw the exact same thing.

        A workplane must be active when the rectangle is drawn, since
        the workplane defines the meaning of "horizontal" and "vertical".

    <h3>Circle</h3>

        This entity is specified by its center point, by its diameter,
        and by its normal.

        To create the circle, choose Sketch -> Circle, and then left-click
        the center. Then release the mouse button; the diameter of
        the circle is now being dragged. Left-click again to place
        the diameter.

        If a workplane is active, then the center point must lie in
        that workplane, and the circle's normal is parallel to the
        workplane's normal (which means that the circle lies in the
        plane of the workplane).

        If no workplane is active, then the center point is free in space,
        and the normal may be dragged (or constrained) to determine the
        circle's orientation.

    <h3>Arc of a Circle</h3>

        This entity is specified by its center point, the two endpoints,
        and its normal.

        To create the arc, choose Sketch -> Arc of a Circle, and then
        left-click one of its endpoints. Then release the mouse button;
        the other endpoint is now being dragged. The center is also being
        dragged, in such a way as to form an exact semi-circle.

        Left-click again to place the other endpoint, and then drag the
        center to the desired position. The arc is drawn counter-clockwise
        from the first point to the second.

        The arc must be drawn in a workplane; it cannot be drawn in
        free space.

        Tangent arcs may be created automatically. To do so, first select
        a point where two line segments join. Then choose Sketch ->
        Arc of a Circle; the arc will be created, and automatically
        constrained tangent to the two line segments.

        The initial line segments will become construction lines, and
        two new lines will be created, that join up to the arc.

        The arc's diameter may then be constrained in the usual way, with
        Distance / Diameter or Equal Length / Radius constraints. This
        is a simple way to round a sharp corner.

    <h3>Bezier Cubic Segment</h3>

        This entity is specified by its four Bezier points: two endpoints,
        and two (in general, off-curve) control points.

        To create the Bezier cubic, choose Sketch -> Bezier Cubic
        Segment. Then left-click one endpoint of the cubic segment.
        Release the mouse button; the other endpoint of the cubic segment
        is now being dragged.

        The two control points are intially placed on the straight line
        between the endpoints; this means that the cubic originally
        appears as a straight line. Drag the control points to produce
        the desired curve.

    <h3>Text in a TrueType Font</h3>

        This entity is defined by two points, at the top left and bottom
        left of the text. The distance between the points determines the
        height of the text; the angle of the line between them determines
        the orientation of the text, and their position determines the
        text's position.

        To create the text, choose Sketch -> Text in TrueType Font. Then
        left-click the top left point of the text. The bottom right point
        of the text is now being dragged; left-click again to place it.

        To change the font, select the text entity. A list of installed
        fonts appears in the text window; click the font name to select
        it. To change the displayed text, select the text entity and
        click the [change] link in the text window.
        

<h2>Constraints</h2>
    
    <h3>General</h3>

        To create a constraint, first select the geometry to be
        constrained. For example, when constraining the distance between
        two points, first select those two points. Then choose the
        appropriate constraint from the Constrain menu.

        Depending on what is selected, the same menu item may generate
        different constraints. For example, the Distance / Diameter menu
        item will generate a diameter constraint if a circle is selected,
        but a length constraint if a line segment is selected. If the
        selected items do not correspond to an available constraint,
        then SolveSpace will display an error message, and a list of
        available constraints.

        Most constraints are available in both 3d and projected versions.
        If a workplane is active, then the constraint applies on the
        projection of the geometry into that workplane. If no workplane
        is active, then the constraint applies to the actually geometry
        in free space.

        For example, consider the line shown below:

        <img src="/pics/ref-projd-constraint.png" />

        The line's length is constrained in two different ways. The upper
        constraint, for 50 mm, applies to its actual length. The lower
        constraint, for 40 mm, applies to the length of its projection
        into the xy plane. (The xy plane is highlighted in yellow.) The
        dotted purple lines are drawn to indicate the locations of the
        line segment's projected endpoints.

        In normal operation, the user activates a workplane (or a
        workplane is activated automatically, for example by creating a
        "Sketch in New Workplane" group). The user then draws an entity,
        for example a line. Since a workplane is active, the line is
        created in that workplane. The user then constrains that line,
        for example by specifying its length. Since the workplane is
        still active, the constraint actually applies to the projection
        of the line segment into the workplane.

        In this case, the projected distance is equivalent to the
        3d distance. If the line segment lies in the workplane, then
        the projection of that line segment into the workplane is just
        that line segment. This means that when drawing in a workplane,
        most of this can be ignored.

        It's possible to use projected constraints in more complex ways,
        though. For example, the user might create a line segment in
        workplane A, and constrain its projection into workplane B.

        Constraints are drawn in purple on the sketch. If a constraint
        has a label associated with it (e.g. a distance or an angle), then
        that label may be repositioned by dragging it with the mouse. To
        modify the dimension, double-click the label; a text box will
        appear on the screen, where the new value can be entered. Press
        enter to commit the change, or Esc to cancel.

    <h3>Failure to Solve</h3>

        In some cases, the solver will fail. This is usually because the
        specified constraints are inconsistent or redundant. For example,
        a triangle with internal angles of 30, 50, and 90 degrees is
        inconsistent--the angles don't sum to 180, so the triangle could
        never be assembled. This is an error.

        A triangle with internal angles constrained to 30, 50, and 100
        degrees is also an error. This is not inconsistent, because the
        angles do sum to 180 degrees; but it's redundant, because only
        two of those angles need to be specified.

        If the sketch is inconsistent or redundant, then the background
        of the graphics window is drawn in red (instead of the usual
        black), and an error is displayed in the text window:

        <img src="/pics/ref-inconsistent.png" />

        As a convenience, SolveSpace calculates a list of constraints
        that could be removed to make the sketch consistent again. To
        see which constraints those are, hover the mouse over the links
        in the text window; the constraint will appear highlighted in
        the graphics window. By deleting one or more of the constraints
        in that list, the user can make the sketch consistent again.

        A different type of error occurs when the solver fails to
        converge. This may be a defect in the solver, or it may occur
        because impossible geometry was specified (for example, a
        triangle with side lengths 3, 4, and 10; 3 + 4 = 7 < 10), In
        that case, a similar error message is displayed, but without a
        list of constraints to remove to fix things. The problem can be
        resolved by removing or editing the constraints, or by choosing
        Edit -> Undo.


    <h3>Reference Dimensions</h3>

        By default, the dimension drives the geometry. If a line segment
        is constrained to have a length of 20.00 mm, then the line
        segment is modified until that length is accurate.

        A reference dimension is the reverse: the geometry drives the
        dimension. If a line segment has a reference dimension on its
        length, then it's still possible to freely change that length,
        and the dimension displays whatever that length happens to be. A
        reference dimension does not constrain the geometry.

        To convert a dimension into a reference dimension, choose
        Constrain -> Toggle Reference Dimension. A reference dimension
        is drawn with "REF" appended to the displayed length or angle.
        Double-clicking a reference dimension does nothing; the
        dimension is specified by the geometry, not the user, so it is
        not meaningful to type in a new value for the reference dimension.

    <h3>Specific Constraints</h3>

        To get help on a specific constraint, choose its menu item without
        first selecting any entities. An error message will be displayed,
        listing all of the possibilities.

        In general, the order in which the entities are selected doesn't
        matter. For example, if the user is constraining point-line
        distance, then they might select the point and then the line, or
        the line and then the point, and the result would be identical.
        Some exceptions exists, and are noted below.

    <h3>Distance / Diameter</h3>

        This constraint sets the diameter of an arc or a circle, or the
        length of a line segment, or the distance between a point and
        some other entity.

        When constraining the distance between a point and a plane, or
        a point and a plane face, or a point and a line in a workplane,
        the distance is signed. The distance may be positive or negative,
        depending on whether the point is above or below the plane. The
        distance is always shown positive on the sketch; to flip to the
        other side, enter a negative value.

    <h3>Angle</h3>

        This constraint sets the angle between two vectors. A vector
        is anything with a direction; in SolveSpace, line segments and
        normals are both vectors. (So the constraint could apply to
        two line segments, or to a line segment and a normal, or to two
        normals.) The angle constraint is available in both projected
        and 3d versions.

        The angle must always lie between 0 and 180 degrees. Larger or
        smaller angles may be entered, but they will be taken modulo
        180 degrees. The sign of the angle is ignored.

        When two lines intersect, four angles are formed. These angles
        form two equal pairs. For example, the pictured lines interesect
        at 30 degrees and 150 degrees. These two angles (30 and 150) are
        known as supplementary angles, and they always sum to 180 degrees.

        <img src="/pics/ref-line-cross-angles.png" />

        (Notice that in the sketch, three of the angle constraints are
        reference dimensions. Given any one of the angles, we could
        calculate the other three; so a sketch that specified more than
        one of those angles would be overconstrained, and fail to solve.)

        When a new angle constraint is created, SolveSpace chooses
        arbitrarily which supplementary angle to constrain. An arc is
        drawn on the sketch, to indicate which angle was chosen. As the
        constraint label is dragged, the arc will follow.

        If the wrong supplementary angle is constrained, then select the
        constraint and choose Constrain -> Other Supplementary Angle. A
        constraint of 30 degrees on one supplementary angle is exactly
        equivalent to a constraint of 150 degrees on the other.

    <h3>Horizontal / Vertical</h3>

        This constraint forces a line segment to be horizontal or
        vertical. It may also be applied to two points, in which case
        it applies to the line segment connecting those points.

        A workplane must be active, because the meaning of "horizontal"
        or "vertical" is defined by the workplane.

        It's good to use horizontal and vertical constraints whenever
        possible. These constraints are very simple to solve, and will
        not lead to convergence problems. Whenever possible, define
        the workplanes so that lines are horizontal and vertical within
        those workplanes.

    <h3>On Point / Curve / Plane</h3>

        This constraint forces two points to be coincident, or a point
        to lie on a curve, or a point to lie on a plane.

        The point-coincident constraint is available in both 3d and
        projected versions. The 3d point-coincident constraint restricts
        three degrees of freedom; the projected version restricts only
        two. If two points are drawn in a workplane, and then constrained
        coincident in 3d, then an error will result--they are already
        coincident in one dimension (the dimension normal to the plane),
        so the third constraint equation is redundant.

        When a point is constrained to lie on a circle (or an arc of
        a circle), the actual constraint forces the point to lie on
        the cylindrical surface through that circle. If the point and
        the circle are already coplanar (e.g., if they are both drawn
        in the same workplane), then the point will lie on the curve,
        but otherwise it will not.

    <h3>Equal Length / Radius</h3>

        This constraint forces two lengths, angles, or radiuses to
        be equal.

        The equal-angle constraint requires four vectors as input:
        the two equal angles are the angle between each pair of inputs.
        For example, select line segments A, B, C, and D. The constraint
        forces the angle between lines A and B to be equal to the angle
        between lines C and D. If the wrong supplementary angle is chosen,
        then choose Constrain -> Other Supplementary Angle, as for the
        angle constraint.

    <h3>Length Ratio</h3>

        This constraint sets the ratio between the lengths of two line
        segments. For example, if line A and line B have length ratio
        2:1, then the constraint is satisfied if A is 50 mm long and B
        is 25 mm long.

        The order in which the lines are selected matters; if line A is
        selected before line B, then the ratio is length of A:length of B.

    <h3>At Midpoint</h3>

        This constraint forces a point to lie on the midpoint of a line.

        The at-midpoint constraint can also force the midpoint of a line
        to lie on a plane; this is equivalent to creating a datum point,
        constraining it at the midpoint of the line, and then constraining
        that midpoint to lie on the plane.

    <h3>Symmetric</h3>

        This constraint forces two points to be symmetric about some
        plane. Conceptually, this means that if we placed a mirror at
        the symmetry plane, and looked at the reflection of point A,
        then it would appear to lie on top of point B.

        The symmetry plane may be specified explicitly, by selecting a
        workplane. Or, the symmetry plane may be specified as a line in
        a workplane; the symmetry plane is then through that line, and
        normal to the workplane. Or, the symmetry plane may be omitted;
        in that case, it is inferred to be parallel to either the active
        workplane's vertical axis or its horizontal axis. The horizontal
        or vertical axis is chosen, depending which is closer to the
        configuration in which the points were initially drawn.

    <h3>Perpendicular</h3>

        This constraint is exactly equivalent to an angle constraint
        for ninety degrees.

    <h3>Parallel / Tangent</h3>

        This constraint forces two vectors to be parallel. 

        In 2d (i.e., when a workplane is active), a zero-degree angle
        constraint is equivalent to a parallel constraint. In 3d, it
        is not.

        Given a unit vector A, and some angle theta, there are in general
        infinitely many unit vectors that make an angle theta with A. (For
        example, if we are given the vector (1, 0, 0), then (0, 1, 0),
        (0, 0, 1), and many other unit vectors all make a ninety-degree
        angle with A.) But this is not true for theta = 0; in that case,
        there are only two, A and -A.

        This means that while a normal 3d angle constraint will restrict
        only one degree of freedom, a 3d parallel constraint restricts
        two degrees of freedom.

        This constraint can also force a line to be tangent to a curve.
        In order to do this, the line must already share an endpoint with
        the curve; this would usually be achieved with a point-coincident
        constraint. The constraint will force them to also be tangent
        at that point.

    <h3>Same Orientation</h3>

        This constraint forces two normals to have the same orientation.

        A normal has a direction; it is drawn as an arrow in that
        direction. The direction of that arrow could be specified by
        two angles. The normal specifies those two angles, plus one
        additional angle that corresponds to the twist about that arrow.

        (Technically, a normal represents a rotation matrix from one
        coordinate system to another. It is represented internally as
        a unit quaternion.)

        For example, the picture below shows two workplanes, whose
        normals are constrained to be parallel:

        <img src="/pics/ref-parallel-normals.png" />

        Because the normals are parallel, the planes are parallel. But one
        plane is twisted with respect to the other, so the planes are not
        identical. The line on the left is constrained to be horizontal
        in the leftmost plane, and the line on the right is constrained
        to be horizontal in the rightmost. These lines are not parallel,
        even though the normals of the workplanes are parallel.

        If we replace the "parallel" constraint with a "same orientation"
        constraint, then the two workplanes become identical, and the
        two horizontal lines become parallel.

        This is a useful constraint when building an assemblies; a single
        "same orientation" constraint will fix all three of the imported
        part's rotational degrees of freedom.

    <h3>Comment</h3>

        A comment is a single line of text that appears on the drawing.
        When the comment is created, it appears in the center of the
        screen. To move the comment, drag it with the mouse. To change
        the text, double-click it.

        The comment has no effect on the geometry; it is only a
        human-readable note.


<h2>Groups</h2>

    <h3>General</h3>

        To view a list of groups, go to the home page of the text window.
        This is accessible from the link at the top left of the text
        window, or by pressing Esc. To view a group's page, click on
        its name in the list.

        All groups have a name. When the group is created, a default name
        (e.g., "g008-extrude") is assigned. The user may change this name;
        to do so, go to the group's page in the text window, and choose
        [rename].

        Groups that create a solid (e.g. extrudes or sweeps) have a "MERGE
        AS" option, which is displayed in the page in the text window.
        The group can be merged as union, which adds material to the
        model, or as difference, which cuts material away.

        These groups also have a color, which determines the color of
        the surfaces they produce. To change the color, click on one of
        the swatches in the group's page in the text window.

        The group's page in the text window also includes a list of all
        requests, and of all constraints. To identify a constraint or a
        request, hover the mouse over its name; it will appear highlighted
        in the graphics window. To select it, click on the link in the
        text window. This is equivalent to hovering over and clicking
        the actual object in the graphics window.

    <h3>Sketch in 3d</h3>

        This creates a new empty group, in which the user may draw lines,
        circles, arcs, and other curves.

        The ultimate goal is usually to draw closed sections (like
        a triangle, or a square with a circular cutout, or some more
        complicated shape). These sections are the input for later groups.
        For example, an extrude group takes a flat section, and uses it
        to form a solid.

        If all of the entities in the group can be assembled into closed
        loops, then the area that the loops enclose is shaded in very
        dark blue. This is the area that would be swept or extruded or
        lathed by a subsequent group.

    <h3>Sketch in New Workplane</h3>

        This creates a new empty group, similar to a new "Sketch in 3d".
        The difference is that a "Sketch in New Workplane" also creates
        a workplane. The workplane is created based on the entities that
        are selected when the sketch is created. These may be:

        A point and two line segments

            The new workplane has its origin at the specified point. The
            workplane is parallel to the two lines. If the point is a
            vertex on a face of the part, and the two lines are two edges
            of that face, then the resulting workplane will be coincident
            with that face (i.e., the user will be drawing on that face).

        A point

            The new workplane has its origin at the specified point. The
            workplane is orthogonal to the base coordinate system; for
            example, its horizontal and vertical axes might lie in the
            +y and -z directions, or +x and +z, or any other combination.

            The orientation of the workplane is inferred from the
            position of the view when the workplane is created; the
            view is snapped to the nearest orthographic view, and the
            workplane is aligned to that.

            If a part consists mostly of ninety degree angles, then this
            is a quick way to create workplanes.

        The new group's associated workplane is automatically set to be
        the active workplane.

        If the entities in this group do not form closed curves, then
        an error message is displayed on the screen, and a red line is
        drawn across the gap. An error is also displayed if the curves
        are not all coplanar.

    <h3>Step Translating</h3>

        This group takes geometry in the active group, and copies it
        multiple times along a straight line.

        If a workplane is active when the step translating group is
        created, then the translation vector must lie parallel to that
        workplane. Otherwise, the translation vector may go anywhere in
        free space.

        The number of copies to create is specified by the user. To
        change this value, click the [change] link in the group's page
        in the text window.

        The copies may be translated on one side, or on two sides. If
        the copies are translated on one side, then the original will
        appear to the left of (or above, below, etc.) all the copies. If
        the copies are translated on two sides, then the original will
        appear in the center of the copies.

        The copies may be translated starting from the original,
        or starting from copy #1. If the translation starts from the
        original, then the translation will contain the original. (So
        a 1-element step will always produce the input geometry in its
        original location.) If the translation starts from copy #1, then
        the original is not included in the output. (So a 1-element step
        makes a single copy of the input geometry, and allows the user
        to translate it anywhere in space.)

        If the active group is a sketch (sketch in 3d, sketch in new
        workplane), the the sketch is stepped and repeated. In that case
        the user would typically draw a section, step and repeat that
        section, and then extrude the step and repeat.

        If the active group is a solid (extrude, sweep, lathe), then
        the solid is stepped and repeated. In this case, the user would
        draw a section, extrude the section, and then step and repeat
        the extrusion.

        In some cases, these two possibilities (extrude the step, vs.
        step the extrusion) are equivalent. If the translation vector
        isn't parallel to the section plane, then only the second option
        will work.

    <h3>Step Rotating</h3>

        This group takes the geometry in the active group, and copies
        it mutiple times along a circle.

        Before creating the group, the user must select its axis of
        rotation. One way to do this is to select a point, plus either
        a line segment or a normal; the axis of rotation goes through
        the point, and is parallel to the line segment or normal.

        If a workplane is active, then it's also possible to select
        just a point; in that case, the axis of rotation goes through
        that point, and is normal to the workplane. This means that the
        rotation remains within the plane of the workplane.

        The step and repeat options (one side / two sides, with original /
        with copy #1) are the same as for step translating groups.

        The numer of copies is specified in the same way as for step
        translating. If the rotated geometry has not yet been constrained,
        then the copies will be spaced evenly around a circle; for
        example, if 5 copies are requested, then the spacing will be
        360/5 = 72 degrees.

        To place the copies along less than (or more than) a complete
        circle, drag a point on one of the copies with the mouse; all
        of the rest will follow, as the step rotation angle is modified.
        Constraints (for example an angle constraint, or a point-on-lie
        constraint) may be used to specify the angle of rotation exactly.

    <h3>Extrude</h3>

        This group takes a flat section, and extrudes it to form a solid.
        The flat section is taken from the section of the group that
        is active when the extrude group is created. (This is usually
        a sketch in workplane, or a sketch in 3d, but could also be a
        step and repeat.)

        The sketch may be extruded on one side, or on two sides. If the
        sketch is extruded on one side, then the new solid is either
        entirely above or entirely below the original sketch. Drag a
        point on the new surface to determine the extrude direction,
        and also to determine the extrude depth. Once the extrusion
        depth looks approximately correct, it may be specified exactly
        by using constraints. For example, the user might constrain the
        length of one of the newly extruded edges.

        If the sketch is extruded on two sides, then the original sketch
        lies at the exact midpoint of the new solid. This means that
        the solid is symmetric about the original sketch plane. Later
        dimensioning often becomes simpler when the part has symmetry,
        so it's useful to extrude on two sides whenever possible.

        If a workplane is active when the group is created, then the
        extrude path is automatically constrained to be normal to that
        workplane. This means, for example, that a rectangle is extruded
        to form a rectangular prism. The extrusion has one degree of
        freedom, so a single distance constraint will fully constrain it.
        This is usually the desired behaviour.

        If no workplane is active when the group is created, then the
        extrude path may be in any direction. This means that a rectangle
        could be extruded to form a parallelepiped. The extrusion has
        three degrees of freedom. This is not typically useful.

        By default, no workplane is active in a new extrude group. This
        means that constraints will apply in 3d; for example, a length
        constraint is a constraint on the actual length, and not on the
        length projected into some plane. This is typically the desired
        behaviour, but it's possible to activate a workplane in the usual
        way (by selecting it, then choosing Sketch -> In Workplane).

    <h3>Lathe</h3>

        This group takes a flat sketch, and sweeps it around a
        specified axis, to form a solid of revolution. The section
        is taken from the group that is active when the lathe group
        is created.

        To create a lathe group, first select a line segment. Then choose
        New Group -> Lathe. The line segment is the axis of revolution.

        The section must not intersect itself as it is swept along the
        curve. If the section crosses the axis of rotation, then it is
        certain to intersect itself and fail.

    <h3>Sweep</h3>

        This group takes a flat sketch, and sweeps it along an arbitrary
        trajectory. The section is taken from the group that is active
        when the sweep group is created. The path is taken from the
        group that precedes the active group.

        The section to sweep should be drawn approximately normal
        (perpendicular) to the trajectory. As the section is swept,
        it is maintained normal to the trajectory.

    <h3>Helical Sweep</h3>

        This group takes a flat sketch, and sweeps it along a helix. The
        section is taken from the group that is active when the helical
        sweep is created.

        To create a helical sweep, first select a line segment and a
        point. Then choose New Group -> Helical Sweep. The line segment
        is the axis of the helix, and the point determines the radius
        of the helix.

        To change the parameters of the helix, enter new values in the
        helical sweep's page in the text window. For example, a 1/2"-10
        screw thread has axial pitch 0.100" per turn (since ten turns
        of 0.100" make an inch), and dRadius = 0. A flat coil has axial
        pitch zero, but some dRadius. A sweep with nonzero pitch and
        dRadius produces a conical helix.

    <h3>Import / Assemble</h3>

        In SolveSpace, there is no distinction between "part" files and
        "assembly" files; it's always possible to import one file into
        another. An "assembly" is just a part file that imports one or
        more other parts.

        The imported file is not editable within the assembly. It is
        imported exactly as it appears in the source file, but with an
        arbitrary position and orientation. This means that the imported
        part has six degrees of freedom.

        To move (translate) the part, click any point on the imported
        part and drag it. To rotate the part, click any point and Shift+
        or Ctrl+drag it. The position and orientation of the part may be
        fixed with constraints, in the same way that any other geometry
        is constrained.

        The Same Orientation constraint is particularly useful when
        importing parts. This one constraint completely determines the
        imported part's rotation. (Select a normal on the imported part,
        select some other normal to constrain it against, and choose
        Constrain -> Same Orientation).

        Import groups have a special "MERGE AS" option: in addition
        to the usual "union" and "difference", they have "assemble".
        The "assemble" option is identical to "union", except that
        it displays a warning if the components intersect with each
        other. This is useful when checking to see if the assembled parts
        interfere. If the parts interfere, then a warning is displayed
        underneath the "MERGE AS" line in the group's text window page.
        The interfering surfaces are also highlighted in the graphics
        window, in red with black stripes.

        When an assembly file is loaded, SolveSpace loads all of the
        imported files as well. If the imported files are not available,
        then an error occurs. When transfering an assembly file to another
        computer, it's necessary to transfer all of the imported files
        as well.

<h2>Analysis</h2>

    <h3>Trace Point</h3>

        SolveSpace can draw a "trail" behind a point as it moves. This
        is useful when designing mechanisms. The sketch shown below is
        a four-bar linkage:

        <img src="/pics/ref-point-traced.png" />

        As the linkage is worked, the midpoint of the top link moves
        along the cyan curve. This image was produced by drawing the
        linkage, tracing that midpoint, and then dragging the linkage
        through its full range of motion with the mouse.

        To start tracing, select a point, and choose Analyze -> Trace
        Point. When the point moves, a cyan trail will be drawn behind it.

        To stop tracing, choose Analyze -> Stop Tracing. A dialog
        will appear, with the option to save the trace as a CSV
        (comma-separated value) file. To save the trace, enter a
        filename. To abandon the trace, choose Cancel or hit Esc.

        The trace is saved as a text file, with one point per line. Each
        point appears in the format x, y, z, separated by commas. Many
        programs, including spreadsheets like Excel, can read this format.
        The units for the coordinates are determined by the export
        scale factor. (If the export scale factor is 1, then they are
        millimeters, and if it's 25.4, then they're inches.)

        If the mechanism is worked by dragging it with the mouse, then
        the points in the trace will be unevenly spaced, because the
        motion of the mouse is irregular. A plot of x vs. y (like the
        cyan trace above) is not affected, but a plot of x or y vs. t
        is useless, because the "speed" along the curve is not constant.

        To avoid this problem, move the point by stepping a dimension,
        rather than by dragging with the mouse. Select the dimension to
        be stepped; this can be any distance or angle. Choose Analyze ->
        Step Dimension. Enter the new final value for that dimension,
        and the number of steps; then click "step dimension now".

        The dimension will be modified in multiple steps, and solved
        at each intermediate value. For example, consider a dimension
        that is now set to 10 degrees. The user steps this dimension to
        30 degrees, in 10 steps. This means that SolveSpace will solve
        at 12 degrees, then 14 degrees, then 16, and so on, until it
        reaches 30 degrees.

        The position of the traced point will be recorded at each
        intermediate value. When the trace is exported, it represents
        the position of that point, as the dimensioned link rotates with
        constant angular speed.

        The step dimension feature can also improve convergence. In some
        difficult cases, the solver will fail to find a solution when a
        dimension is changed. If the specified constraints have multiple
        solutions, then the solver may also find an undesired solution. In
        this case, it may be useful to try stepping the dimension to
        its new value, instead of changing it in a single step.

    <h3>Measure Volume</h3>

        This feature reports the volume of the part. Depending on
        the active units, the volume is given in cubic inches, or in
        millilitres and cubic millimeters.

        If the part contains smooth curves (e.g. circles), then the
        mesh is not an exact representation of the geometry. This means
        that the measured volume is only an approximation; for a mesh
        that looks fairly smooth on-screen, expect an error around one
        percent. To decrease this error, choose a finer chord tolerance.


<h2>Export</h2>

    <h3>Bitmap Image</h3>

        This option will export a bitmap image of whatever is displayed
        on-screen. It is equivalent to taking a screenshot. This option
        is useful for producing human-readable output.

        Choose File -> Export Image. The file is exported as a PNG,
        which most graphics software can open.

    <h3>2d Vector (DXF)</h3>

        This option will generate a 2d vector file that represents a
        specified plane in the part. Most 2d CAM software, including
        the software that ships with most laser or waterjet cutters,
        will accept a DXF file.

        Before exporting a DXF, it is necessary to specify which plane of
        the part should be exported. This may be specified by:

        a face:

            Any surfaces coplanar with that plane face will appear in the
            file. The faces must be shown before they can be selected;
            click the link in the third line of the text window.

        a point, and two lines or vectors:

            The export plane is through the point, and parallel to
            the two lines or vectors. If the two lines or vectors are
            perpendicular, then they will become the x and y axis in the
            DXF file. Whichever line is more horizontal in the current
            view becomes the x axis, and the other one becomes the y.

            This means that it's possible to rotate the exported DXF
            through ninety degrees by rotating the view through ninety
            degrees (in the plane of that face). Similarly, by rotating
            the part around to look at the face from behind instead of
            in front, the exported DXF is mirrored.

        the active workplane

            If a workplane is active, and nothing is selected when the
            export command is chosen, then SolveSpace will export any
            surfaces that are coplanar with the active workplane. The
            workplane's horizontal and vertical axes become the x and
            y axis in the DXF file.

        The units of the DXF file are determined by the export scale
        factor, which may be specified in the configuration screen.

        The exported DXF contains only line segments; all curves are
        broken down into lines, with the specified chord tolerance.

    <h3>3d Mesh (STL)</h3>

        This option will generate a 3d triangle mesh that represents
        the entire part. Most 3d CAM software, including the software
        for most 3d printers, will accept an STL file.

        The mesh from the active group will be exported; this is the
        same mesh that is displayed on screen. The coordinate system
        for the STL file is the same coordinate system in which the part
        is drawn. To use a different coordinate system (e.g., to rotate
        or translate the part), create an assembly with the part in the
        desired position, and then export an STL file of the assembly.

        The units of the STL file are determined by the export scale
        factor, which may be specified in the configuration screen.

<h2>Configuration</h2>

    <h3>Material Colors</h3>

        In the text window screen for certain groups (extrude, lathe,
        sweep), a palette of eight colors is displayed. This palette
        allows the user to choose the color of any surfaces generated
        by that group.

        These eight colors are specified here, by their components.
        The components go from 0 to 1.0. The color "0, 0, 0" is black,
        and "1, 1, 1" is white. The components are specified in the order
        "red, green, blue".

        A change to the palette colors does not change the color of any
        existing surfaces in the sketch, even if the color of an existing
        surface no longer appears in the palette.

    <h3>Light Directions</h3>

        The 3d part is displayed with simulated lighting, to produce
        the impression of depth. The directions and intensities of these
        lights may be modified according to user preference.

        The lights do not have a position; they have only a direction,
        as if they were coming from very far away. This direction is
        specified in 3 components, "right, top, front". The light with
        direction "1, 0, 0" is coming from the right of the screen.
        The light with direction "-1, 0, 0" is coming from the left of
        the screen. The light with direction "0, 0, 1" is coming from
        in front of the screen.

        The intensity must lie between 0 and 1. A light with intensity
        0 has no effect, and 1 is full brightness.

        Two lights are available. If only one is desired, then the second
        may be disabled by setting its intensity to zero. When the part
        is rotated or translated, the lights do not move.

    <h3>Chord Tolerance</h3>

        SolveSpace does not represent curved edges or surfaces exactly.
        Any curves are broken down into piecewise linear segments,
        and surfaces are represented as triangles.

        This introduces some error. The chord tolerance determines how
        much error is introduced; it is the maximum distance between
        the exact curve and the line segments that approximate it. If
        the chord tolerance is decreased, then more line segments will
        be generated, to produce a better approximation.

        The chord tolerance is specified in units of screen pixels. This
        means that when the user zooms in on the model, a better
        approximation is produced.

        The same tolerance is used for the mesh that's displayed on
        screen, and for the mesh that is used to export to a file. It
        may be helpful to use a large chord tolerance (2-5 pixels) while
        drawing, for fast response, and then temporarily specify a small
        chord tolerance (~0.5 pixels) before exporting an STL or DXF file.

    <h3>Perspective Factor</h3>

        To display a 3d part on-screen, it must be projected into 2d. One
        common choice is a parallel projection. In a parallel projection,
        any two lines that are parallel in real life are also parallel
        in the drawing. A parallel projection is also known as an
        axonometric projection. Isometric and orthographic views are
        examples of parallel projections.

        Another way to transform the image into 2d is with a perspective
        projection. In a perspective projection, objects closer to the
        "camera" appear larger than objects that are farther away. This
        means that some lines that are parallel in real life will not be
        parallel in the drawing; they will converge at a vanishing point.

        The image below is a perspective projection. All of the square
        cutouts are the same size, but the ones at the front (closer to
        the viewer) are drawn larger, and the ones at the back are drawn
        smaller.

        <img src="/pics/ref-perspective.png" />

        The next image is a parallel projection. All of the square
        cutouts are the same size on the drawing. (The cutouts at the
        top might look slightly larger, but that is an optical illusion,
        because the eye is accustomed to seeing images with perspective.)

        <img src="/pics/ref-no-perspective.png" />

        A perspective projection will often look more realistic, and
        gives a better impression of depth. The disadvantage is that
        the perspective distorts the image, and may cause confusion.

        By default, SolveSpace displays a parallel projection. To display
        a perspective projection, set the perspective factor to something
        other than zero. The distance from the "camera" to the model is
        equal to one thousand pixels divided by the perspective factor.

    <h3>Edge Color</h3>

        The surfaces of the 3d part are shaded according to the specified
        lighting. Different faces will catch the light at slightly
        different angles, and will therefore appear slightly brighter
        or darker. This permits the viewer to distinguish the boundary
        between the faces.

        Depending on the lighting, this may not provided very much
        constrast. To make the edges of the part more visible, it's
        possible to emphasize them with a solid-color line.

        If the edge color is specified as "0,0,0", then no emphasized
        edges will be drawn. If any other color is specified, then the
        edges will be drawn in that color. The edge color is specified
        in the same format as for the material color.

    <h3>Export Scale Factor</h3>

        Internally, SolveSpace represents lengths in millimeters. Before
        exporting geometry to an STL or DXF file, these lengths are
        divided by the export scale factor. This scale factor determines
        the units for the exported file.

        If the scale factor is set equal to 1, then exported files are
        in millimeter units. If the scale factor is set equal to 25.4,
        then the exported files are in inch units, since 1 inch = 25.4 mm.

        SolveSpace works in a right-handed coordinate system. If the
        scale factor is negative, then the exported file will appear in
        a left-handed coordinate system (so that a right-handed screw
        thread will become left-handed).

<h2>Licensing</h2>

    As downloaded, SolveSpace does not include a license key. This means
    that it cannot create files with more than six groups. Larger files
    may be opened, but not modified. This light version of SolveSpace
    is intended for evaluation, but non-commercial / personal use is
    also permitted.

    The licensed version of SolveSpace can create files with an unlimited
    number of groups.

    When a license is purchased, a license file ("solvespace.key")
    will be sent via email. To activate the license, save this file
    somewhere on your computer. In SolveSpace, choose Help -> Load
    License... A file dialog box will appear; select the license file.

    No license server or dongle is required, and licenses do not expire.



This is the introductory tutorial. We review the basic user interface,
and draw a simple 2d part. This covers rectangles, symmetry constraints,
distance/length constraints, and equal length constraints.

We draw a slightly more complex part, by combining multiple extrusions.
This introduces workplanes and Boolean ops, and several new constraints.

We look at constraints in more detail. This covers inconsistent
and nonconverging sketches (two common error conditions), projected
constraints in 3d, reference dimensions, and construction geometry.

We look at step and repeat; this takes entities, and copies them multiple
times along a line (translating) or the arc of a circle (rotating). The
details of the step are specified using constraints.

We build an assembly from multiple parts. The positions and orientations
of the parts are enforced using constraints. We run a computed
intersection check, to verify that the parts don't interfere.

We draw linkages and other mechanisms, and simulate their operation using
the constraint solver. The trajectory of certain points on the linkage
is traced and exported. We also attach a linkage to a solid model,
and animate the solid model by dragging the linkage.