The purpose of Image Match Generator is to make a set of "standard" images of a 3D object. Other sofware converts those images to image signatures. Image signatures can be stored in a database. Given a new image signature, one can find similar image signatures in the database.
To use Image Match Generator, you need to install Blender 2.74 or later.
:pyimage_match_generator.py
is a Python script but you don't need to install Python to use it. That's because Blender comes bundled with a version of Python (currently Python 3.4) and it uses that.
All 3D objects are assumed to be modeled using STL files. Those STL files are assumed to be in subdirectories of a directory.
:pyimage_match_generator.py
has a command-line interface.
The simplest use of :pyimage_match_generator.py
has the form:
$ blender -b -P image_match_generator.py -- -d ~/stl_set_a/ -o test_output/
blender -b
launches Blender in the background (rather than launching the Blender GUI).-P image_match_generator.py
tells Blender to run the Python script named :pyimage_match_generator.py
.- The double dash (
--
) indicates the beginning of the arguments for the Python script (i.e. not for Blender). -d ~/stl_set_a/
tells the Python script that the directory with subdirectories containing STL files is~/stl_set_a/
.-o test_output/
tells the Python script that the generated images should be written to the directorytest_output
. If that directory doesn't exist, it will be created.
In this case, 48 images get generated, plus a report file named image_match_generator_report.csv
. Each generated image file will have a filename similar to:
cf4a7d5060943dd196b1e34fb6cfbf74.2.3.back.1.png
Here's what that filename means:
cf4a7d5060943dd196b1e34fb6cfbf74
is a hash of the name of the directory containing the STL file (not the name of the STL file).- The
.2
following that means the camera was at one end of eigenvector 2. Eigenvector 0, 1, and 2 are the three eigenvectors of the moment of inertia matrix of the object (treating it as a hollow shell). That is, they are the three principal axes. - The
.3
following that means the object was rotated by 3/4 of a full rotation (270 degrees). That slot can have the values 0, 1, 2, and 3. - The
.back
means the camera was at the back end of the eigenvector, not the front end. - The
.1
means the the object was reflected. If it had been.0
then that would mean it wasn't reflected.
The default image resolution is 1024px by 1024px, but that can be changed using the --resolution RESOLUTION
argument. For example, to render images that are 200px by 200px, use something like:
$ blender -b -P image_match_generator.py -- -d ~/stl_set_a/ -o test_output/ --resolution 200
By default, for each of the three eigenvectors, both the front and back view will be generated, and for each of those four rotations will be generated, and for each of those two reflections will be generated. That makes 3x2x4x2 = 48 images total. You can turn off any or all of front+back, rotations, or reflections using the following flags:
--no-rotations
--only-front-view
--no-reflections
You can use one, two, or all three of those flags together. For example, here's how you'd use all three, so only three images would be generated (the front view of three eigenvectors):
$ blender -b -P image_match_generator.py -- -d ~/stl_set_a/ -o test_output/ --no-rotations --only-front-view --no-reflections
By default, Blender isn't used to render every image, because rendering is computationally expensive. Instead, whenever possible, image rotations or image reflections are used instead. Collectively, those are known as image transforms. You can turn off image transforms using the --no-image-transforms
flag. If you do, every image will be generated by reflecting or rotating the object, rendering that object, and then unrotating and unreflecting the object as necessary.
When generating images for the database, you want all 48 images, so just call :pyimage_match_generator.py
as in the simplest use case.
When generating images for search, you only need a small number of images, say three or six.
To get help with Image Match Generator from the command line, use
$ blender -b -P image_match_generator.py -- -h
Here's the current output:
usage: blender [-h] [--resolution RESOLUTION] [--no-rotations]
[--only-front-view] [--no-reflections] [--no-image-transforms]
d o
Generate oriented images for image matching
positional arguments:
d directory containing STL files
o directory where to put images
optional arguments:
-h, --help show this help message and exit
--resolution RESOLUTION
resolution of renderings (n x n)
--no-rotations do not generate rotations
--only-front-view only generate front views
--no-reflections do not generate reflections
--no-image-transforms
generate all images by rendering