What is 3DOptix?

The fastest, most intuitive, non-sequential, ray tracing, cloud-based, optical system simulation software.

3DOptix’s innovative GPU and cloud-based ray tracing engine can trace billions of rays per second, faster than any other simulation software on the market. Our easy-to-use application enables you to easily design both simple and complex optical systems and make smart decisions based on real data. 3DOptix Warehouse is the first ever cloud-based workspace for sharing optical designs. With numerous designs available, the 3DOptix Warehouse offers engineers an unparalleled resource for exploring new ideas, discovering innovative solutions, and finding great starting points for their own designs.

API Python Wrapper

Our API python wrapper is released in a beta version and has only limited features support at the moment. We are working on supporting more features and you can expect new versions to come out soon.

Features

The API contains the following abilities:

• Get information about your current setups.
• Choose setup to work on.
• Change position and rotation of simulation parts.
• Run simulations on the cloud.

And it has the following logic and terminology:

• Get: Used to get the basic information about the element (setup, part, etc), such as id and name.
• Fetch: Used to request deeper information about the chosen element, such as setup's parts or part's position and rotation.
• Update: Used to push changes that were made locally to 3DOptix systems.
• Run: Used to execute simulations on 3DOptix systems.

Installation

API python wrapper installation is available using PyPi:

pip install threed-optix

Get your API key from 3DOptix user interface (under "user settings"):

• Click on your email, and choose "user settings" in the drop-down
• On the buttom of the settings manu, click on "API"
• Copy your API key

Begin

The API consists of:

• ThreedOptixAPI object, that communicates with our server.
• Setup object, that contains information about a simulation setup.
• Part object, that holds the information about a setup part.
• AnalysisResult object, which handles the simulation results data.
• Vector3 object, which allows to transform and rotate the parts.

Import and authenticate:

import threed_optix as tdo
​
#Your API key from 3DOptix user interface
api_key = '<your_api_key>'
​
#api is the object that manages the communication with 3DOptix server
api = tdo.ThreedOptixAPI(api_key)

Get a list of your 3DOptix setups:

#'setups' will be a list of your simulation setups, each one has a name and id
setups = api.get_setups()

Choose the simulation setup you want to work on:

First, we need to identify the setup we want to work on:

#Examine the setups:
for s in setups:

    print(p.label, p.id)

Note A setup id is unique, but the name is not unique

Then, we can fetch more information about the setup:

#Chosen setup name (Be careful- setup name doesn't have to be unique)
setup_id = '<your setup id>'
​
#Get the 'tdo.Setup' object to work on
setup = None
for s in setups:
​​
    #Get your setup by name
    if s.id == setup.id:
        setup = s​
        break
​
assert setup is not None, "Setup was not found"
​
# Fetch setup parts and information
# The method updates the setup object parts
api.fetch_setup(setup)

Warning Currently, a setup needs to be run in the user interface at least one time in order for api.fetch_setup to work

Change Simulation Setups

We can change the properties of setup parts. At the moment, we support changing the position and rotation of parts. We can identify each part with its id and label properties.

Access setup parts:

# 'parts' will be a list of the optical elements, lasers and detectors in the setup
parts = setup.get_parts()

Choose the part that you want to modify:

First, we need to identify the part we want to work on:

#Examine the parts of the setup
for p in parts:

    print(p.label, p.id)

Note A part id is unique, but the label is not unique

Then, we can fetch more information about the part and start working:

import copy

#Chosen part id
part_id = '<the id of the part to change'

#Get the 'tdo.Part' object to work on
part = None
for p in parts:
​
    #Get part by id
    if p.id == part_id:
       part = p
       break
​
assert part is not None, "Part was not found"
​
#Fetch the part data
# The methods update the part object position and rotation
api.fetch(part)
​
#Before you make any changes, we recommend to import copy and store the original part with deepcopy:
original_part = copy.deepcopy(part)

Change Rotation

Each part has a part.change_rotation method, which enables to change the rotation with respect to the x, y, and z axis, using tdo.Vector3 object. Rotation is stated using degrees.

#Define the rotation
new_rotation = tdo.Vector3(90, 0, 45)
​
#Apply on the part
part.change_rotation(new_rotation)

Note Changing a part rotation like that does not automatically updates the changes to the system

Change Position

Each part has a part.change_position method, which enables to change the part x, y, and z locations relative to their primary coordinate system, using tdo.Vector3 object. Position change is stated in mm.

#Define changes
new_position = tdo.Vector3(1, 0.5, 3)
​
#Apply on the part
part.change_position(new_position)

Note Changing a part position like that does not automatically updates the changes to the system

Update Part

In order to update the local changes to the original setup in the 3DOptix interface, we need to use api.update method:

#Update the changes
api.update(part)
​
#Since we stored the original part, we could always restore it
api.update(original_part)

Run Simulations And Analyze

Run Simulation

Running the simulation on the cloud is really simple:

#run the simulation
result = api.run(setup)
​
#fetch the data
api.fetch(result)
​
#Get the results as a pandas DataFrame:
data = result.data
​
#Save the data locally
data_path = 'path/to/save/data'
data.to_csv(data_path)

Results

Results are a pd.DataFrame object where each line is a single ray. The columns are:

• Ox, Oy, Oz: The origin point of the ray for each axis.
• Dx, Dy, Dz: The initial direction of the ray for each axis.
• Hx, Hy, Hz: The hit position of the ray for each axis.
• wavelength: The wavelength of the ray.
• Ap: The p amplitude of the ray.
• hit_surface_idx: The index of the surface that the ray hit, when -1 means no hit.
• source_idx: The index of the light source that generated the ray.

License

3DOptix API is available with MIT License.