match3d¶

Manual setup¶

$ sudo add-apt-repository ppa:thomas-schiex/blender
$ sudo apt-get update
$ sudo apt-get install blender

$ pip install -e .

Using Docker¶

Run elasticsearch:

$ docker-compose up -d es

Then to start an ipython session:

$ docker-compose run --rm m3d ipython

API operations¶

The most important functionality is provided in api_operations.py.

from match3d.api_operations import APIOperations
api = APIOperations(index_name='3d_test')

index_name is the name of the elasticsearch index to use. Defaults to match3d if none is specified.

api.add('human', stl_url='http://people.sc.fsu.edu/~jburkardt/data/stla/humanoid_tri.stl')
api.add('human_other', stl_url='http://people.sc.fsu.edu/~jburkardt/data/stla/humanoid.stl')

api.add('porsche', stl_file='/home/ryan/Downloads/porsche.stl')

api.search(stl_file='/home/ryan/Downloads/porsche.stl')

{'/home/ryan/Downloads/porsche.stl':
    {
        u'human_other': 0.44157460914354879,
        u'porsche': 0.0
    }
}

api.search('http://people.sc.fsu.edu/~jburkardt/data/stla/humanoid.stl')

{'http://people.sc.fsu.edu/~jburkardt/data/stla/humanoid.stl':
    {
        u'human': 0.13292872986279264,
        u'human_other': 0.0,
        u'porsche': 0.24738691224575407}
}

api.list_designs()

[u'porsche', u'human_other', u'human']

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¶

$ blender -b -P image_match_generator.py -- -d ~/stl_set_a/ -o test_output/ --resolution 200

--no-rotations
--only-front-view
--no-reflections

$ blender -b -P image_match_generator.py -- -d ~/stl_set_a/ -o test_output/ --no-rotations --only-front-view --no-reflections

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

Overview¶

This Python Blender script produces images, one image per STL file, showing nine renderings of the 3D object pasted into a single image as a \(3x3\) collage. The idea is to have one image that can give a human a good sense of what the 3D object is. The camera positions are chosen to be fairly evenly distributed on a sphere (not randomly).

Usage¶

Example usage:

$ blender -b -P generate_images_for_humans.py -- -d ~/Documents/ascribe/cad_files/testset1/ -o test_out_dir

The -d argument is the directory containing subdirectories which contain STL files. All of those subdirectories will be scanned and the STL file they contain will be rendered.

The -o argument is the output directory where all the final images will be saved. If that directory doesn’t exist yet, it will be created. Each image is named after the parent directory of the associated STL file.

Note that we’re assuming that each subdirectory contains only one STL file.

Building the documentation¶

To build the docs, simply run

$ docker-compose up bdocs

Or if you prefer, start a bash session,

$ docker-compose run --rm bdocs bash

and build the docs:

root@a651959a1f2d:/usr/src/app/docs# make html

Viewing the documentation¶

You can start a little web server to view the docs at http://localhost:50080/

$ docker-compose up -d vdocs

Making changes¶

The necessary source code is mounted, which allows you to make modifications, and view the changes by simply re-building the docs, and refreshing the browser.