Added README

README.md

+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.
+               )