About Image Match Generator¶
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.
Prerequisites¶
To use Image Match Generator, you need to install Blender 2.74 or later.
image_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.
Assumptions¶
All 3D objects are assumed to be modeled using STL files. Those STL files are assumed to be in subdirectories of a directory.
image_match_generator.py
has a command-line interface.
Example 1¶
The simplest use of image_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 namedimage_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.
Command Line Arguments¶
Image Resolution¶
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
Turning off Rotations, Front+Back, and/or Reflections¶
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 \(3 x 2 x 4 x 2 = 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
Turning off Image Transforms¶
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.
Generating Images for the Database¶
When generating images for the database, you want all 48 images, so just call
image_match_generator.py
as in the simplest use case.
Generating Images for Search¶
When generating images for search, you only need a small number of images, say three or six.
Getting Help from the Command Line¶
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