diff --git a/solidify/README b/solidify/README new file mode 100644 index 0000000..cba208e --- /dev/null +++ b/solidify/README @@ -0,0 +1,237 @@ +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. + + +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. This file must not yet exist. Solidify + store 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 a 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.