Using Sys.Argv To Read Command Line Arguments In Blender Python

What are Command Line Arguments and sys.argv in Python?

Command line arguments are values passed to a program when it is invoked from the command line interface. They allow the user to customize the behavior of the program on runtime. In Python, the sys module provides access to command line arguments through the sys.argv list. The first element of this list is always the name of the script itself, and subsequent elements are the arguments passed.

The sys.argv feature gives Python scripts flexibility and modularity. Arguments passed through the command prompt can alter the flow of the program or provide contextual data like file paths or user preferences. Scripts can perform different actions depending on the options and values they receive.

Definition and purpose of command line arguments

Command line arguments, often shortened to command-line args or CLA, are input parameters passed to a program during runtime. They are used to feed contextual data into the script about how to operate or what data to use. For example, a Python script that processes images could accept the image file path, output folder path, resize dimensions, etc. as arguments instead of hardcoding them.

Table of Contents

The purpose of CLAs is to make programs and scripts adaptable and reusable. Developers can build functionality without needing to change the code itself by relying on arguments to provide context and configurability.

Introduction to sys.argv for accessing arguments in Python

The sys.argv feature of Python gives access to all command line arguments passed to a script. It is implemented as a list containing the script name as the 0th element followed by all arguments. For example, if a script named script.py is invoked with “python script.py -n 5 file.txt output”, sys.argv would be:

sys.argv[0] = ‘script.py’
sys.argv[1] = ‘-n’
sys.argv[2] = ‘5’
sys.argv[3] = ‘file.txt’
sys.argv[4] = ‘output’

The sys module containing sys.argv must be imported before use. Arguments can then be read from the list and validated. This allows scripts to leverage command line arguments for configuration and execution options without needing to hardcode them within the logic. Developers can change behavior without touching source code.

Using sys.argv in Blender

Importing sys module in Blender Python

To access command line arguments with sys.argv in a Blender Python script, first import the sys module. This is done at the top of the file with:

import sys

This imports the entire sys module and gives access to constants, functions, and values like sys.argv for reading arguments passed to Blender or the script.

Getting command line arguments with sys.argv

With sys imported, command line arguments can be read from sys.argv as a list. For example:

import sys

arg1 = sys.argv[1] 
arg2 = sys.argv[2]

print(f'Arguments passed: {arg1} {arg2}')

This prints the first two arguments after the script name. Remember indices start at 1 rather than 0 since sys.argv[0] contains the script name.

Values can be validated and processed as needed once assigned to variables. Input for options like enabling debug mode or setting output paths can be handled by checking sys.argv for expected flags and values.

Example code for reading arguments

Here is some example code for handling a few command line arguments in a Blender Python script:

import sys
import bpy

debug = False
if '-d' in sys.argv:
  debug = True
  
infile = 'default.blend'  
outfile = 'output.png'

for i in range(len(sys.argv)):
  if sys.argv[i] == '-i':
    infile = sys.argv[i+1]
  elif sys.argv[i] == '-o':
    outfile = sys.argv[i+1]
    
print(f'Input: {infile}') 
print(f'Output: {outfile}')
print(f'Debug: {debug}')

# Rest of script logic with args loaded

This handles a debug flag, input file path, and output file path from arguments. Multiple arguments can be processed this way to configure the script’s execution.

Passing Arguments to Blender from Terminal/Command Prompt

Syntax for passing arguments when launching Blender

To pass command line arguments to a Blender Python script, they need to be provided after the Blender executable path when launching it. On Windows the syntax is:

path\to\blender.exe -P myscript.py -- arg1 arg2 arg3

On Linux and macOS the syntax is similar:

/path/to./blender -P myscript.py -- arg1 arg2 arg3

The -P flag runs the specified script on launch. The — delineates Blender arguments from script arguments. Everything after — gets put in sys.argv.

Example commands for passing multiple arguments

To extend the example script from the previous section, here is a launch command passing multiple arguments on Windows:

C:\Program Files\Blender\blender.exe -P process.py -- -i files/scene.blend -o images/render.png -d

And the same on Linux:

/usr/local/blender/blender -P process.py -- -i files/scene.blend -o images/render.png -d

This includes the input file, output file, and debug flag arguments. The script logic would load them into variables via sys.argv for use in its processing flow.

Use Cases and Examples

Common use cases for command line arguments in Blender

Here are some common use cases and examples of how command line arguments are leveraged in Blender Python scripts:

Input/output paths – File system locations are often passed as arguments for input data like models or scenes and output renderings, simulations, etc.
Operational modes – Arguments can set scripts into modes like debug/verbose logging, dry run no-ops, or variants like draft quality vs final.
Parameters/configuration – Countless parameters can be passed instead of hard-coded: render size, particle counts, physics steps.
Action flags – Arguments may simply be binary or text flags denoting certain actions like “export”, “render”, “simulate”.
Job data – In production pipelines, identifiers and cached data may be passed detailing assets, shots, and steps.

Arguments turn general scripts into customizable tools. Most Blender Python scripts accept some arguments rather than needing edited source for each use case. They promote reusability and adaptability.

Example scripts showing sys.argv usage

As a simple example, here is a Python script that uses command line arguments to control output file format and printing debug info:

import sys
import bpy

format = 'PNG'
debug = False

if '-png' in sys.argv:
  format = 'PNG'
elif '-jpg' in sys.argv:
  format = 'JPG'
  
if '-d' in sys.argv:
  debug = True

print(f'Format: {format}')

if debug:
  print('DEBUG info printing enabled')
  
# Render logic with format applied

And it could be invoked from the CLI as:

blender -P render_script.py -- -png -d

More complex examples include scripts for rendering scene collections, running physics simulations, compiling asset libraries, even full production pipeline tools.

Tips and Best Practices

Validation and error handling for arguments

Like any external input, it’s important to validate command line arguments in case invalid data is passed unintentionally or maliciously. Here are some tips:

Check argument length to ensure required parameters are passed
Use type checks to validate numbers, paths, identifiers
Wrap logic in try/except blocks to catch issues gracefully
Provide useful error output for diagnosing problems

Catching issues early and clearly makes debugging easier. Arguments should have sane defaults where possible as well.

Best practices for command line arguments

Document expected arguments and syntax in script comments
Use intuitive, consistent argument names and patterns across scripts
Apply validation and sanity checks on argument values
Make arguments and script behavior easy to understand
Support flexibility in arguments to increase reusability

Following best practices ensures scripts using command line arguments are usable, robust, and maintainable.