iso direction reference frame does not follow source.position.rotation，if it was locked to global Z-axis despite source rotation？

[QiLHong]

Description

I am trying to simulate a CBCT setup using OpenGATE (v10). My goal is to place a source on the X-axis (e.g., [500, 0, 0]) and have it emit a cone beam pointing towards the center (direction [-1, 0, 0]).

I am using a GenericSource with iso direction distribution, restricted by theta and phi to create the cone shape. By default, the iso distribution seems to be aligned with the global Z-axis.

The Problem

I attempted to rotate the source orientation using source.position.rotation (rotating 90 degrees around the Y-axis) and attached it to a volume, explicitly setting source.direction_relative_to_attached_volume = True.

However, the emission direction (the axis of the cone) remains fixed along the global Z-axis in the simulation. It appears that the iso direction distribution ignores the rotation of the source/attached volume, even when the relative flag is enabled.

I want to avoid using type="focused" or type="beam" because I need to maintain physical correctness with weight=1 for isotropic emission in a medical physics context.

Minimal Code Snippet

Here is the configuration I used. I expected the cone to rotate and point towards the center, but it still points up (Z-axis).

from scipy.spatial.transform import Rotation
import opengate as gate

# ... inside the simulation setup ...

# 1. Create a Gantry volume (Box) at X = 500 mm
gantry = sim.add_volume("Box", "Gantry")
gantry.size = [20*cm, 5*cm, 5*cm]
gantry.translation = [500*mm, 0, 0] 
gantry.material = "G4_AIR"

# 2. Define Source
source = sim.add_source("GenericSource", "MySource")
source.attached_to = gantry.name
source.particle = "gamma"

# 3. Attempt to rotate the source to point to -X
# Default iso is Z-axis. Rotating 90 deg around Y should make it point to -X (or X).
rot = Rotation.from_euler('y', 90, degrees=True).as_matrix()

# I apply the rotation to the source position
source.position.rotation = rot

# 4. Enable relative direction 
# (This is supposed to make the emission direction follow the rotation, but it seems to fail for 'iso')
source.direction_relative_to_attached_volume = True

# 5. Define Cone Beam using iso
source.direction.type = "iso"
source.direction.theta = [0, 20 * deg]
source.direction.phi = [0, 360 * deg]

# Note: I also tried setting source.position.type = "disc" hoping the normal vector would rotate, 
# but the emission axis remained global Z.

Expected Behavior
The axis of the cone beam should follow the rotation of the source (or the attached volume). In this case, since the source/gantry is rotated 90 degrees, the cone axis should point along the X-axis (towards the center).

Actual Behavior
The cone beam is still emitted along the global Z-axis (perpendicular to the desired direction), as verified in the visualization (lines go up/down instead of horizontal).

Questions
Is direction_relative_to_attached_volume intended to work with the iso direction type in OpenGATE v10?

If this is not a bug, what is the recommended way to rotate the reference frame of an iso source so that the cone axis points to an arbitrary direction (e.g., -X)?

Environment
OpenGATE version: [Insert your version here, e.g., 10.0]

Python version: [Insert your version here, e.g., 3.10]

OS: [Insert your OS here, e.g., Windows 10 / Ubuntu 22.04]

[Joshua-Dias-Barreto]

Short Answer

Your minimal code snippet works as expected, the cone axis points along the X axis only if the source is rotated (as written in your script). If you rotate the gantry and rotate the source as well, their rotations cancel out and the axis of the cone is along the Z axis.

Long Answer

The docs for sources say that "Rotation of the volume is with respect to the attached volume", since the source rotation is applied relative to the attached volume, rotating both the gantry and the source by the same rotation results in a net identity rotation in world coordinates

Minimal Reproducible Script

Uncomment the line gantry.rotation = rot to see the effect of the rotations cancelling out and the cone axis going back along the Z axis. If only the source is rotated as done in this script, the axis should be along -X.

from scipy.spatial.transform import Rotation
import opengate as gate

if __name__ == "__main__":
    sim = gate.Simulation()
    sim.verbose_level = gate.logger.RUN
    sim.g4_verbose = False
    sim.visu = True
    sim.visu_type = "vrml"   # easy to see directions
    sim.output_dir = "./output"

    mm = gate.g4_units.mm
    m = gate.g4_units.m
    cm = gate.g4_units.cm
    MeV = gate.g4_units.MeV
    deg = gate.g4_units.deg

    world = sim.world
    world.size = [2, 2, 2]
    world.material = "G4_AIR"

    gantry = sim.add_volume("Box", "Gantry")
    gantry.size = [20*cm, 5*cm, 5*cm]
    gantry.translation = [500*mm, 0, 0]
    gantry.material = "G4_AIR"

    rot = Rotation.from_euler("y", 90, degrees=True).as_matrix()
    # gantry.rotation = rot

    source = sim.add_source("GenericSource", "MySource")
    source.attached_to = gantry.name
    source.particle = "gamma"
    source.energy.mono = 1 * MeV
    source.n = 1000

    # Apply the rotation to the source frame
    source.position.rotation = rot

    source.direction_relative_to_attached_volume = True

    source.direction.type = "iso"
    source.direction.theta = [0, 20 * deg]
    source.direction.phi = [0, 360 * deg]

    sim.run()

Environment
OpenGATE version: 10.0.2

Python version: 3.10.13

OS: Ubuntu 20.04