This project is started to convert complex mechanical CAD designs to X3D for convenience
of online browsing. The x3d_step_assy.py runs in FreeCAD and processes STEP models created
by other mechanical CAD programs.

This macro converts assembly CAD model to X3D. It tries to recognize
individual parts (provided as STEP files) in the assembly model, converts
each part to X3D and then generates assembly X3D file that includes inline
references to the recognized part files, applying appropriate transformations
(rotations and translations).

First thing the program does is it scans all the STEP models under the
specified directory and collects general properties of each file, including
volume, surface area, center of mass, gyration radii and axes, as well as
per-color centers. Normally each part should contain just one solid, but if
there are more than one only the largest (by volume) will be used for
identification in the assembly (in that case assembly may show multiple not
matched solids that will still be correctly rendered in the final model with
each part).

This information will be saved in 'info' directory under the specified working
directory, same file name as the original STEP model but with extension
'.pickle' (and yes, they are just Python pickle files). These files are
saved in one directory, so each original part file have to have unique name,
even when stored in different directories. This file basename (last segment
of the OS path without the extension) will be used as a part name and used
in 'id' and 'class' properties of the result x3d files. The program only
processes the part files if the corresponding info file does not exist or
has the modification timestamp earlier than the STEP model.

During the next step the assembly object is analyzed and the same properties
are extracted for each solid, then the each is compared to the library part
and the parts with the same values (to the specified precision) are selected
as potential candidates. Parts material is not used, so distinguish between
similar screws that have the same geometry the color may be used.
This allows to find the position of the center of volume of the part in the
assembly, but getting the correct orientation is trickier. For the asymmetrical
(having all 3 different radii of gyration) it is rather easy (only 4 variants
to check as the gyration axes can have opposite direction), it also works for
the parts with full cylindrical or spherical symmetry where the axes match is not
required, but it is more difficult to deal with the discrete rotational symmetry.
When resolving such cases the program relies on colored faces of the parts.
Coloring just a single hole (not on the axis of the symmetry) in the part
(and then using it in the assembly) breaks ambiguity. Parts that do not have
faces that can be easily colored can be modified with boolean operations that
preserves the shape but add color asymmetry

When the solids are matched, the program generates missing/old (by timestamp) 
x3d files of the individual parts and assembly in the 'x3d' subdirectory of the
working directory. It also generates and shows the parts that are not recognized
(they might be 'other' solids of the part files and so will be available in the
generated model).
 
This method can work with most modern CAD systems, and does not require special
export - the colored STEP files are still good for production. In some systems
the assembly model should be flattened (removed assembly status) before STEP
export, it is also advised to import individual parts that are provided to you
as STEP models to the CAD that is used for the assembly and re-exporting to STEP
so both part and assembly STEP files will be generated by the same software.
               )   
