3. How to make models on the command line

With the Emboss Plane plugin introduced in the previous post we used the Blender user interface (UI) to create our 3D printable models.  But if you need to make a large number of models, slight variations on a single model, or (in the case of Tactile Universe) both, this process can be slow and tedious.  In these cases we can instead run blender directly on the command line and bypass the UI altogether.

EDIT (Feb 24, 2020): For Blender 2.80 or higher make sure to use v4.0 or higher of the plugin.  New features have also been added since these posts were made, updated version will be available soon.

Setting up Blender to run from the command line

To get started we need to set up blender to be run from the command line.  This is outlined nicely in the official documentation.  For me this involved setting up an alias to the blender executable on my Mac (bash shell):

echo "alias blender=/Applications/Blender/blender.app/Contents/MacOS/blender" >> ~/.bash_profile

On the Windows (cmd.exe) this is:

DOSKEY blender="C:\Program Files\Blender Foundation\Blender\blender.exe"

Installing all plugins

If you have not installed our plugins via the UI, you can do so on the command line.  Download the latest release of our code from GitHub, navigate to the directory and run:

blender -b --python install_all_addons.py

Setting up your directory structure

For this example let’s create models for two different galaxies, M51 and M100.

To start we will set up our directory structure.  Each galaxy will go into its own folder and the make_model.py and TU_startup.blend files from our github page should be placed in the same directory as these folders.  This should look something like this:

TU_galaxy_examples
├── M51
│ └── M51_i.png
├── M100
│ └── M100_i.png
├── make_model.py
└── TU_startup.blend

You can download example directories and batch scripts that are already set up for either UNIX based systems or  Windows.

Making configuration files

The command line script requires a configuration json file to be passed in, this file contains all the information needed to crate a model.  This file is structured as follows:

{
  "input_file_path": "M51_i.png",
  "plane_height": 112,
  "emboss_plane_keywords": {
    "Fpu": 2,
    "Emboss_height": 3,
    "Base_height": 3,
    "Border_width": 3,
    "External_edge": "TOP"
  },
  "filter_size": 1.0,
  "stl_keywords": {
    "axis_forward": "Z",
    "axis_up": "X"
  },
  "output_path": "/path/to/output/folder",
  "output_name": "M51_i"
}

Not all of these parameters need to be specified and will default to reasonable values. Here is a breakdown of these parameters:

• input_file_path: The full path to the image being used to create the model (if no file path is specified it will assume the image is in the same folder the code is being run from).
• plane_height: The height of the resulting model in mm (default 112 mm)
• emboss_plane_keywords: The keywords passed into the emboss plane plugin
  • Fpu: Faces per unit (default 2)
  • Emboss_height: How high should a white pixel be raised about a black one (default 3 mm)
  • Base_height: How far below black should the model extend (default 3mm)
  • Border_width: The width of the outside border (default 3mm)
  • External_edge: What edge to remove from the model to be printed as a separate object (default “NONE”)
• filter_size: Size in pixels of a blur filter applied to the image.  This is useful for noisy images (default 1px)
• stl_keywords: Keywords passed into the stl export function
  • axis_forward: What axis should be treated as the forward direction (default “Y”)
  • axis_up: What axis should be treated as the up direction (default “Z”)
• output_path: The full path to the folder the stl and blend files will be saved (defaults to the folder the code is run from).  NOTE: for Windows make sure all slashes in the path are escaped, e.x. "C:\\Users\\Name\\Folder\\"
• output_name: The name to used for the output stl and blend files

For our example we will create configuration files for “top edge off” and “all edges on” version of the model.  For M51 the “top edge off” config looks like:

 

{
  "input_file_path": "M51_i.png",
  "emboss_plane_keywords": {
     "External_edge": "TOP"
  },
  "stl_keywords": {
    "axis_forward": "Z",
    "axis_up": "X"
  },
  "output_name": "M51_i_top_edge_off"
}

and the “all edges on” looks like:

{
  "input_file_path": "M51_i.png",
  "output_name": "M51_i_all_edges_on"
}

Similar files should be created for M100 as well.  The directory structure should now look like this:

TU_galaxy_examples
├── M51
│ ├── M51_i.png
│ ├── i_top_off.json
│ └── i_all_on.json
├── M100
│ ├── M100_i.png
│ ├── i_top_off.json
│ └── i_all_on.json
├── make_model.py
└── TU_startup.blend

Running the code

With your terminal in the top level directory you can run the script to make one model with the following command (bash):

cd M51
blender ../TU_startup.blend --python-exit-code 1 --python ../make_model.py -- i_top_off.json

Or on Windows:

cd M51
blender ..\TU_startup.blend --python-exit-code 1 --python ..\make_model.py -- i_top_off.json

This will crate two files: M51/M51_i_top_edge_off.stl and M51/M51_i_top_edge_off.blend.  The final step is to create a bash script that will look for all sub folders and json files and create a mode for each.  This script will be called process_configs.sh and will sit in the top level directory (bash).

#!/bin/bash
set -e

for d in */; do
  cd $d
  for config in $(ls *.json); do
    echo $d$config
    blender ../TU_startup.blend --python-exit-code 1 --python ../make_model.py -- $config > /dev/null
  done
  cd ..
  echo '======'
done

To run this code type source process_configs.sh into the terminal.

On Windows this script should be called process_configs.bat and will look like:

set PATH=%PATH%;"C:\Program Files\Blender Foundation\Blender\"

for /D %%d in (*) do (
  cd %%d
  for %%c in (*.json) do (
    @echo %%d\%%c
    blender.exe ..\TU_startup.blend --python-exit-code 1 --python ..\make_model.py -- %%c
  )
  cd ..
  @echo ======
)

To run this code type process_configs.bat into the terminal or by double-clicking the file.

The final file structure

Once the code is done running the final file structure will look like:

TU_galaxy_examples
├── M51
│ ├── M51_i.png
│ ├── i_top_off.json
│ ├── i_all_on.json
│ ├── M51_i_top_edge_off.stl
│ ├── M51_i_top_edge_off.blend
│ ├── M51_i_all_edges_on.stl
│ └── M51_i_all_edges_on.blend
├── M100
│ ├── M100_i.png
│ ├── i_top_off.json
│ ├── i_all_on.json
│ ├── M100_i_top_edge_off.stl
│ ├── M100_i_top_edge_off.blend
│ ├── M100_i_all_edges_on.stl
│ └── M100_i_all_edges_on.blend
├── make_model.py
├── TU_startup.blend
└── process_configs.sh

In the next blog post we will cover how to make name plates for each model.