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.