File:        Readme.htm
   Summary:     Geodesica-SFX 0-9-9-9 Distribution Info.
   Author:      Nicholas Shea
   Copyright:   (c) Nicholas Shea 2000-2021
   Email:       nicholas-shea@talktalk.net
   Web:         http://www.neolithicsphere.com/geodesica/index.htm
                             IMPORTANT NOTICE
Geodesica-SFX comes in two builds: Geodesica-SFX-Mesa and Geodesica-SFX-OpenGL.

Geodesica-SFX-Mesa uses software rendering and is slower than the OpenGL version
but provides the correct fog depth-cue for labels when using the latest graphic
cards; it is still perfectly usable for frequencies up to 12V.

Only use Geodesica-SFX-Mesa if Geodesica-SFX-OpenGL does not run on your PC or
the fog depth-cue for labels does not render correctly.

Geodesica-SFX has been tested on the following platforms:

    Windows-XP 32 bit (service pack 3)
    Windows 7 64 bit
    Windows 10 Pro 1903 64 bit.


    Geodesica-SFX is an OpenGL(r) quad-edge Geodesic modelling program that is
    designed to make advanced geodesic construction fun and easy to understand. 
    The program can generate a variety of envelopes for both Primal and Dual,
    whilst advanced cross-target tensegrity spaceframes may be built between
    envelopes. For example:
       a) Union Tank Car Dome spaceframe.
       b) Eden Project Dome spaceframe.

    Lengths, angles, dihedrals, e.t.c., can be measured interactively with
    labels identifying the respective components.

    Unique sets can be generated for struts, hubs and cells, with each set being
    coloured individually. Component connectivity is printed to the Log Window.
    Geodesica can distribute vertices over ellipsoidal envelopes using a pseudo-
    magnetic field where field strength is governed by a bezier curve.

    Geodesica was inspired by the work of Franz Dischinger and Buckminster
    Fuller; the program was originally written as my own accompaniment to the 
    book entitled 'Geodesic Math and How To Use It' by Hugh Kenner.

    My intention is to make Geodesica a quality product that implements sound
    numeric methods, with a consistent interface and clear documentation. I hope
    one day to build a life size dome using Geodesica. Until that time the
    program remains untested (by me) in real world applications.

    Geodesica-SFX requires registration to:
    1. Export files.
    2. Draw hubs plans (for ring flange and star flange hubs).
    3. Enable full logging functions.

    Geodesica-SFX is the commercial fork of 'Geodesica' which can still be 
    obtained on sourceforge. Geodesica-SFX is NOT open source. Geodesica-SFX can 
    only be downloaded from the Geodesica home page at:

    Geodesica-SFX is programmed in C++ using a modified version of the
    WildMagic(r) 3 graphics engine; the UI was built with the FLTK toolkit.
    Geodesica runs on UNIX(r)/Linux(r) (X11), Microsoft(r) Windows(r).
    Both Linux and Windows versions are 32 bit.


    Unarchive the zip to your chosen directory. Geodesica does not touch the
    Windows registry. The expanded folder should look something like this:
          Data              [folder]
          Export-Tests      [folder]
          ScreenShots       [folder]
          UnitTest-Output   [folder]
          Geodesica.exe     [program binary]
    Do not rename any of the folders or mix old Data folders with new ones.
    Please ensure that you have read/write access to the installation directory 
    as Geodesica-SFX must be able to write its logs and preferences.
    The 64 bit binaries run in Windows 10 without using 'Compatibility Mode'.
    But if you are using a 32 bit Geodesica binary on a version of Windows later
    than XP, Geodesica must be run in 'Compatibility Mode' for Windows XP
    (Service pack 3). Right-click on the program icon and choose 'Properties'.
    Use the following settings:


    Click 'Apply' then 'OK'.
    Launch Geodesica by double clicking the program icon.

    Geodesica will show the splash screen. A few seconds later the main window
    will appear with the text "Initialising..." in the top left hand corner.
    The app should only take a few moments to start. Typical launch times are:
    CPU                   OS                               LAUNCH TIME
    AMD Athlon XP1800     Windows XP [service pack 3]      Approx. 3 seconds
    AMD A6 5400           Windows 10 Pro [1903]            Approx. 5 seconds
    If Geodesica-SFX does not run on your machine an e-mail would be
    appreciated so I can look into the problem.


    Unarchive the zip to your home folder. Geodesica does not touch the /usr
    When running under Wine, please ensure your have installed the minimum
    required Windows fonts (eg Courier, etc). For example, on Knoppix-8.6 this
    entails copying the required fonts from C:/Windows/Fonts to
    Ensure you have write access to the installation directory.

      Select, Analyse or Modify, depending on the Pick mode. Set the pick mode
      on the toolbar. There are three tabs corresponding to each mode. Each
      mode has a sub-mode. For example, on the 'Select' tab there are buttons
      for single item selection and group selection. The other buttons on the
      'Select' tab determine what gets picked, i.e., Vertices, Edges, Cells, etc.
      Measured dimensions are displayed in the log window.
      Click an object to select, click again to deselect.
      Passive highlighting can be turned off in the Select menu.
      Click and drag for Trackball rotation.
      Mouse Wheel moves in and out of scene along camera heading vector.
      NOTE: for comprehensive navigation control, use the 'Navigator' window.
      Click in a viewport to change the camera.
      Hold down ALT key and right-click on vertex or hub for a context menu.

      There are 36 different viewport configurations ranging from a single port
      up to 6. The more viewports that are open, the slower the app will run.
      Select a viewport configuration from the View menu.

      All data pertaining to a camera can be changed in the Navigator window.
      Choose menu Window->Navigator. Expand the Navigator window by clicking
      on the small arrows at the bottom left. Expand three levels for Location,
      Orientation and Frustums.
       The Modify tab on the Toolbar has eight options for changing the geometry
       of a primal lattice:
       1. Make Edge.
       2. Kill Edge.
       3. Kill Vertex.
       4. Collapse Edge.
       5. Divide Edge.
       6. Truncate Vertex.
       7. Split & Bevel.
       8. Stellate.
       The modelling tools have not been stress tested, but if the program 
       detects an illegal operation, it will warn the user.
       IMPORTANT: If you see a Topology Warning message, take heed.
       Random deletion tests succeed in removing vertices in 12V spheres until
       only a few remain, and the program correctly handles each case. However,
       the program will eventually crash if the sphere isn't closed. This will
       happen if you delete a vertex or edge that 'splits' the sphere in half,
       or if you create an "island" of edges that are not connected to the
       surrounding manifold. In this instance the lattice can no longer be
       traversed by the Quad-Edge operators. Checks have been put in place to
       try and ensure this does not happen.
       In most cases, Geodesica will label the offending vertex with appropriate
       instructions. You can then use the modelling tools to remedy the
       situation. If all else fails, please rebuild the sphere by changing the
       subdivision frequency.
       NOTE: Editing the Primal model when 'Generate Dual' is ON may be slow on
       legacy CPU's. And even slower if 'Generate Space Frame' is on also. It is
       best to edit the Primal with 'Generate Dual' OFF.

         US IGES Pro 5.3
         Wavefront OBJ
         DXF 14 ascii
       Only visible elements are exported.
   2a. DXF ascii export notes.
       Cells are trifanned and grouped as layers with the following options:
       1. Layer cells by parent group.
       2. Layer cells by parent lattice.
       3. Layer cells individually.
       User is informed if the layers required exceed 20. They usually do.
       When cells are layered individually...
       The cell trifan layer prefix is 'CT_' followed by the cell count
       Cell skeletons are always layered per cell.
       The cell skeleton layer prefix is 'CS_' followed by the cell count.
       Cell spaceframe struts are always layered per cell.
       A spaceframe strut layer prefix is 'SS_' followed by the cell count.
       Only visible cells are exported.
       Currently there is only support for creating cell trifans with DXF.
       Whilst this increases the triangle count for coplanar cells with 3 or
       4 vertices, subdividing a geodesic cell around its centroid is more
       useful than using an arbitrary perimeter vertex.
       As trifans are created during DXF export, user must ensure that cell
       perimeters form 'convex' polygons as in Fig A.
                       A                B
                     _____            ____
                    /     \          |    |
                   /       \         |    |
                   \       /        /   __|
                    \_____/        /   |__
       Trifans are formed around the cell centroid, so the cell in Fig B. will
       not export as a trifan.
       The DXF file currently omits HEADER, TABLES, BLOCKS, and LAYERS.
       According to the AutoCAD DXF reference manual, the following is allowed:
       The entire HEADER section can be omitted if header variables are not set.
       The TABLES section can be omitted if nothing in it is required.
       The BLOCKS section can be omitted if no block definitions are used.
       Layers can be referenced within the ENTITIES section.
       The menus 'Select->All' and 'Select->None' operate according to the
       current Pick Mode. If the 'Pick Vertices' button is on, then all vertices 
       get selected / deselected. If the 'Pick Cells' button is on, then all 
       cells get selected / deselected etc.
       You cannot pick invisible elements. So to pick vertices, for example,
       the 'Pick Vertices' button must be ON in the 'Select' tab, and vertices
       must be visible in the 'Attributes' window.
       Use the toggle buttons 'P', 'D' & 'S' on toolbar to set the pick
       target - Primal, Dual or Spaceframe. When you change to the MODIFY tab,
       the pick target is the Primal only.
       Picking Caveats
       1. Pick mode 'Vertex' when Faces are visible.
       If faces are visible on the Attributes window and the pick mode is
       'Vertex', you can only pick vertices where the pick ray intersects with a
       visible face. In other words, if some faces are hidden so revealing the
       underlying manifold, you cannot pick vertices of that manifold without
       first turning off Show Faces in the Attributes window.
       2. Pick mode 'Edge' when Faces are visible.
       If faces are visible on the Attributes window and the pick mode is
       'Edge', you can only pick edges where the pick ray intersects with a
       visible face. In other words, if some faces are hidden so revealing the
       underlying manifold, you cannot pick edges of that manifold without
       first turning off Show Edges in the Attributes window.
       3. If both Targets A and B are coincident (id est, they have the same
       frequency, breakdown, class and envelopes), the Pick Manager will have
       trouble selecting coincident strut and hub meshes of the same type and
       dimension. This should not be an issue as the whole purpose of the
       Target mechanism is to set different envelope extents for each Target.
       However, if for some reason you have a need for coincident Targets, hide
       one Target with the 'Target' menu, then you can then safely pick the
       A Picking Example
       The spherical coordinates of a picked vertex are displayed in the
       VERTEX EDITOR on the toolbar. You can modify Phi, Theta or Radius by
       editing the field(s) and pressing return. This works for multiple vertex
       selections. For example, you can create an egg shape by setting the
       PRIMAL ENVELOPE to an 'Ellipse profile' with an expansion in Y of 1.5.
       You can then switch to FRONT view by right clicking in the OpenGL view
       and choosing the front camera. Use the AREA-SELECT tool on the toolbar to
       select all PRIMAL vertices below Theta = 90 (negative Y values).
       Then enter 1.0 in Radius field of the VERTEX EDITOR and press return.
       Be sure to use the menu Select->None afterwards.
       If the DUAL ENVELOPE 'Project' option is OFF, the dual will follow the
       same egg profile as the PRIMAL.
       When picking elements, it is preferable to set one PICK TARGET only
       (Primal or Dual, but not both), otherwise confusion may result using
       high frequencies: you might think you've picked an element on the PRIMAL
       hull, when in fact you've picked the DUAL. Note: the hierarchy of the
       picked element is also displayed on the VERTEX EDITOR.
       Be careful picking Vertices or Edges in QuadEdge mode when Facets are
       invisible; if the pick ray does not find an element on the front of the
       sphere, it will travel between Edges and pick elements on the rear
       interior of the sphere. This is a feature, not a bug.

       You can log cell dimensions / angles  strut dimensions / axial angles /
       dihedral angles etc. Please note that results have not been extensively
       verified but match data in 'Geodesic Math and How to Use It' by
       Hugh Kenner. Please consult the file 'Verifying-Output.txt' for details.
       When measuring angles/lengths at a vertex, please make sure that Vertices
       are visible. The button for the corresponding lattice must be down in the
       Attributes window. You cannot pick an invisible vertex. This helps if you
       only want to select Dual vertices or vice-versa.
       IMPORTANT: Before reading off your measurements in the Log Window, please
       consult 'ACCURACY' below.
       The program appears to be accurate and great lengths have been undertaken
       to maintain floating point accuracy, especially when converting between
       spherical and Cartesian coordinates and when projecting to envelopes.
       However, output has only been tested on models and not in a real world
       applications. Please see the page 'Verifying Output' on the website.
       It is best to model a dome with a unit radius (or expansion in Y thereof)
       and then scale the unit radius to the desired dimension. This is done
       using the 'Units' tab which is located on the 'Precision and Units' tab
       of the Preferences Window.
       Scaling the unit radius is far more accurate than making the dome
       life-size by changing the envelope extents. The larger the envelope, the
       greater the probability of errors in projected rays. A ray might only be
       0.0000001 degrees off true, but by the time it intersects with a large
       envelope, the error becomes appreciable. This is rather like plotting a
       course that is, say, 0.2 degrees off: by the time you've flown 20 miles,
       the error is great.
       You can set the working units to anything you like: feet, meters, inches,
       yards etc, and then optionally convert the logged result to any other
       unit. Then when you measure a length, the log will print something like:
          Scale Factor = 3.0000000000
          Units = Meters and Inches
           Radius    A =  3.0000000000 Meters, or 118.1102362200 Inches.
           Radius    B =  3.0000000000 Meters, or 118.1102362200 Inches.
           Distance AB =  3.1543866727 Meters, or 124.1884516812 Inches.
           Central angle = 63.4349488
                = 063° 26' 5.8156800"
       Imperial units are currently represented as decimals. This will be fixed
       in a future release, when I can find a font that represents fractions. In
       the meantime, if you are working in Feet, you can view decimal inches and
       their equivalent fractions by printing up a 'Decimal Inches Table', which
       is accessed in the Log Window's menu.
       It will be interesting to see what difference using MPFR makes to the
       accuracy of modelling life size domes. Depending on available memory and
       processor power, it is possible to work with high target precisions of
       thirty or more decimal places. MPFR is currently only implemented for
       the Utilities.
       Colours and morphs may be applied to single cells or cell groups. Group
       attributes are persistent when a sphere is re-built but individual cell
       attributes are lost.
       Changes in applied colours are not visible until objects are de-selected.
       The application tries to follow the convention of "Select then effect"
       but this behaviour needs refining.
       Example 1
       To colour edges, choose the Group Select tool and click on an edge. The
       edges turn red to show they are selected. Change their colour using the
       colour-well in the Attributes window. Click the edges again to deselect
       them, or choose 'Select->None'. Alternatively, use the 'SELECT ALL'
        toggle on the Attributes window.
       Drawing Round points
       If you have problems drawing round points with your graphics card
       (The selected vertex goes black, for example), then please un-check this
       option. The round points checkbox only activates with the 'Group' select
       Changing my code to use a scene graph has slowed this down. Nevertheless,
       it is still usable and makes an interesting experiment on distributing
       vertices on ellipsoidal envelopes when standard Root-E correction fails
       to give desired results.

       Please consult the file 'Verifying-Output.txt' which describes how to use
       the measuring tools, how to change envelope profiles, and how to log dome
       data to the Log Window. The principal source for verifying output was the
       classic publication 'GEODESIC MATH AND HOW TO USE IT' By Hugh Kenner.

    Geodesica-SFX is NOT open source and is the commercial fork of 'Geodesica'.
    You can still download the open source version 'Geodesica' from the
    SourceForge server. I regret that help cannot be provided with compilation
    as the program links to a modified version of WildMagic 3.
    IMPORTANT: Data files exported by Geodesica-SFX, such as DXF, OBJ and Log 
    output may not be posted on the web, and are for the use of registered users 
    alone. To register Geodesica-SFX please consult 'Registration-Readme.txt'.



    Documentation will be uploaded as the program develops. Please be sure to
    read the file 'Development-Status.txt' for any new features/changes.


    Microsoft and Windows are registered trademarks of Microsoft
    Corporation. UNIX is a registered trademark of the X/Open
    Group, Inc.  OpenGL is a registered trademark of Silicon
    Graphics, Inc.  MacOS is a registered trademark of Apple
    Computers, Inc.


    Geodesica is copyright 2005-2018 by Nicholas Shea
    Geodesica-SFX is copyright 2005-2018 by Nicholas Shea   

 Geodesica 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. Balazar Geodesics shall not be liable for any loss
 of profits, loss of business, loss of information, personal injury, indirect,
 special, incidental or consequential damages, expressly or not set forth
 herein incurred before, during or after the use of Geodesica. Any liability
 of Balazar Geodesics will be limited exclusively to bug fixes or program
 replacement. Except as set forth above, no other warranties, either express
 or implied, including the warranties or conditions of merchantability and
 fitness for a particular purpose are applicable to this product or any of
 the other products which are created by Balazar Geodesics.