cae-tools/solidify/README

solidify - Merge two opposing faces of a part into a solid
==========================================================

Solidify is a tool for adjusting the orientation of two opposing faces
(surfaces) of a three-dimensional part such that they correctly align
with each other, and to generate output that represents the volume
(solid) enclosed between the two faces.
 
This work is distributed under the terms of the GNU GENERAL PUBLIC
LICENSE, Version 2:

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

For your convenience, a copy of the complete license has been included
in the file COPYING.GPLv2.


Theory of operation
-------------------

The shape of a three-dimensional part can be reconstructed by scanning
two opposing faces of the part. The part is then the space between the
two faces.

When doing this in practice, a few problems arise. One of them is that
the faces will not be perfectly opposed. E.g., the part being scanned
may be inclined, rotated, or shifted. Solidify implements the following
operations:

- change the inclination of the part along the x and y axis (i.e., the
  part's z plane is tilted). The general assumption is that the part is
  scanned with its main surfaces parallel to the z plane and that only
  small adjustments are necessary.

- change the part's height above the z plane. There is a conceptual z0
  plane, parallel to the z plane, that is coplanar with a reference
  surface in the face. The height of the z0 plane above the z plane
  can be adjusted.

- set the distance between the z0 plane of the top face and the z0 plane
  of the bottom face. This defines the thickness at some point of the
  part.

- align the two faces by rotating them around the z axis and by shifting
  them in the x and y direction.

Except for setting the distance between z0 planes, all these operations
are interactive. Solidify furthermore provides visual clues that help to
minimize anomalies.

Solidify reads faces as comma-separated point clouds generated by
Dr.Picza3. It outputs a set of files that define the part in POV-Ray.


Starting a project
------------------

For a project, the following information is necessary:

- the name of the project file. If the file does not yet exist, solidify
  starts a new project. Solidify stores information pertaining to the
  project, such as the names of the file containing the faces and the
  orientation set for the faces.

  Solidify project files typically have the extension .sfy.

- two text files containing the two faces as comma-separated point
  clouds. If a file name ends with the extension .bz2, solidify will
  uncompress the file on the fly with bunzip2.

  If instead of a file name a HTTP or HTTPS URL is given, solidify will
  try to download the file with "wget" into a directory called .cache.
  This directory must be manually created for this purpose. On further
  invocations, solidify will load the file directly from the cache.

- the distance between the z0 planes of the two faces. Typically, this
  is the thickness of the part in some area that is flat on both sides.
  The distance is measured in millimeters.

To generate a project name.sfy with the faces top.svn and bottom.sfy
and a z0 distance of 1.5 mm, run

$ solidify name.sfy top.csv bottom.csv 1.5

Solidify will load the faces (this can take a while) and then show the
top face for z0 plane editing.


Leaving solidify
----------------

To exit solidify and save the current settings in the project file,
simply press "q". To quit without saving, terminate solidify by pressing
^C in the shell.


Changing an existing project
----------------------------

Start solidify with the name of the project file, e.g.,

$ solidify name.sfy

Solidify will load the face files and then show the top face for z0
plane editing.


Adjusting the z0 plane
----------------------

There are four buttons at the right side of the screen. The ones labeled
"A" and "B" are for editing the top and bottom faces.

Note that each face has its own z0 plane, which is controlled
independently from the of the other z0 plane.


Display
- - - -

The center area of the screen shows the respective face from the top.
Areas below the z0 plane are shown in red, areas above the z0 plane are
in green. Intersections of the z0 plane with the face are shown in blue.

The intensity of the color increases with the distance between the face
and the z0 plane. To make it easier to see which way the planes are
facing, areas with only a small difference and thus often directly
adjacent to an intersection (blue) are colored with more intense red and
green.

Below and on the right side of the central view, lateral projections of
cuts at the cursor position are shown.


Control
- - - -

The z0 plane is manipulated with the mouse wheel. Rotating the mouse
wheel with the pointer near the center of the main view raises or lowers
the z0 plane. Outside the center, rotating the mouse wheel tilts the z0
plane by pushing or pulling at the pointer position.

The center area is marked with a yellow circle that becomes visible when
approaching it with the mouse pointer.


Workflow
- - - -

There are two objectives when adjusting the z0 plane:

- it should intersect the face at the point(s) that define the distance
  between z0 planes, and

- the z0 plane should be parallel to the principal orientation of the
  part

As a first step, it's usually best to pick one or two flat reference
areas containing the zones where the distance was measures, and to tilt
the z0 plane until it is roughly parallel to these areas. This can be
easily seen on the lateral projections.

Then the z0 plane is be raised or lowered until it intersects. The
result should be a large blue field that covers the reference areas.

If the part is not only tilted but also warped, it may not be possible
to evenly level it. For achieving as good an adjustment as possible, one
should attempt to maximize and evenly distribute the blue areas on the
main view.


Aligning the faces
------------------

When clicking the "A+B" or "B+A" button, both faces are shown
superimposed, with the bottom face rotated around the y axis.

With "A+B", the top face is manipulated, with "B+A" the bottom face.
The display is the same in both cases.


Display
- - - -

The following colors are used:

- white: both faces overlap
- green: only the top face. There are no points in the bottom face at
  this location
- green: only the bottom face
- blue: the top face is below the bottom face


Control
- - - -

Again, the faces are controlled with the mouse wheel and the function of
the wheel depends on whether the pointer is in the central area or not.
The central area is marked with a yellow circle that is displayed when
the mouse pointer approaches it.

To rotate the face around its center, move the mouse pointer outside the
center area and spin the mouse wheel. The larger the distance from the
center, the faster the face spins.

Spinning the mouse wheel when the pointer is inside the central area
shifts the face along the x and y axis. (*) The central circle is
divided into four areas: in the left and right area, the face is shifted
horizontally, in the upper and lower area, the face is shifted
vertically.

(*) When shifting the bottom face, the direction depend on the face's
    rotation. This is a bug but it has no other ill consequences.


Workflow
- - - -

The faces usually don't overlap perfectly. The goal is thus to
distribute the red or green overlaps evenly.

If significant portions of the part are drawn in blue, this means that
the orientation or the height of the z0 planes is not correct.

If the part is very thin, it may be necessary to raise the faces a but
above the z0 plane to keep the faces from intersecting due to warping.


Rendering with POV-Ray
----------------------

                                                                       |
When invoked with the option -p, solidify generates the following three
files:

- name.inc: a POV-Ray file that renders the part. The part is called
  "Part_name"
- name-top.pgm: a PGM (Portable GrayMap) image containing a height field
  for the top face
- name-bot.pgm: height field of the bottom face

Invocation is as follows:

$ solidify -p name.sfy

A part can be used in a POV-Ray scene by #including its name.inc file
and then placing the object.