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 named image_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 directory test_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.

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