Danger

This package is depreciated, use ptr-editor instead.

Attitude Generator Module#

Note

At the moment, only JUICE AGM API interface is publicly available. In the future, the module will be able to run AGM directly if you have it installed locally.

When you have a valid PTR, read from a file with read_ptr() or manually created, you can try to submit it to ESA Attitude Generator Module (AGM) to know if the new attitude is valid and retrieve the generated camera kernel (ck) and resolved ptr (when you have observations block without start or/and stop times).

List the available API endpoints#

To call AGM, you need to identify which metakernel will be use as your baseline. You can get the list of the available metakernels in POINTING_TOOL_ENDPOINTS dictionary. At the moment, only the JUICE_API endpoint is implemented.

from ptr import POINTING_TOOL_ENDPOINTS

POINTING_TOOL_ENDPOINTS['JUICE_API']

/tmp/ipykernel_646/4155192847.py:1: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr import POINTING_TOOL_ENDPOINTS

<PointingToolApi> https://juicept.esac.esa.int | Contexts:
- JUICE Planning Cruise
- JUICE Planning
- JUICE CREMA 5.1 150lb_23_1_b2
- JUICE CREMA 5.1 150lb_23_1_a3
- JUICE CREMA 5.1 150lb_23_1
- JUICE CREMA 5.0

Call AGM programmatically#

from ptr import agm_simulation

In addition to your PTR file, you need to tell AGM which metakernel to use (here JUICE CREMA 5.0) and which endpoint will be called (JUICE_API):

Tip

Instead of calling agm_simulation on example.ptx filename, you can provide a pointing request message directly.

You can also call AGM direct on the PRM object:

prm.simulate('JUICE CREMA 5.0', 'JUICE_API')

results = agm_simulation('JUICE CREMA 5.0', 'example.ptx', 'JUICE_API')

results

✔ Success

    • AGM Endpoint: https://juicept.esac.esa.int/agm
    • Metakernel: juice_crema_5_0_v460_20251104_001
    • <prm>
  <body>
    <segment>
      <data>
        <timeline frame="SC">
            <block ref="OBS">
               <metadata>
                  <comment> Occultation by star HD157056 </comment>
                  <comment>PRIME=JANUS</comment>
                  <solarArrays>
                     <fixedRotationAngle units="deg">-50</fixedRotationAngle>
                  </solarArrays>
               </metadata>
               <startTime> 2032-07-02T04:18:40 </startTime>
               <endTime> 2032-07-02T04:32:00 </endTime>
               <attitude ref="inertial">
                  <boresight ref="SC_Zaxis" />
                  <phaseAngle ref="align">
                     <SCAxis frame="SC">
                        <x> 0 </x>
                        <y> -1 </y>
                        <z> 0 </z>
                     </SCAxis>
                     <inertialAxis ref="EU2SC" />
                  </phaseAngle>
                  <target frame="EME2000">
                     <lon units="deg"> 260.504 </lon>
                     <lat units="deg"> -24.999 </lat>
                  </target>
               </attitude>
            </block>
        </timeline>
      </data>
    </segment>
  </body>
</prm>
    • CK: https://juicept.esac.esa.int/agm_output/20260401T190629153418/output/juice_sc_ptr.bc
    • Resolved PTR: https://juicept.esac.esa.int/agm_output/20260401T190629153418/output/ptr_resolved.ptx
    • timeqxqyqzqw
    • Session ID: 20260401T190629153418

As you can see, this simulation was successful. You can expand the results and explore the log if you need more details.

Hint

The calculations are cached locally to avoid, duplication requests if PTR was already submitted.

If you need to save this ck locally, you can do:

results.ck.save('example.ck')

PosixPath('example.ck')

You can also download the resolved PTR computed by AGM:

results.ptr_resolved.save('agm_resolved.ptx')

PosixPath('agm_resolved.ptx')

Use AGM results with spiceypy#

The AGMResults object retrieved after the simulation (here results) is compatible with spiceypy and can be used as a regular kernel file.

spiceypy.furnsh(results)

In that case, the generated ck from the simulation will be download and put into the SPICE Pool.

Call AGM from the command line interface#

You can query AGM directly from the command line in Jupyter notebooks and in your terminal:

Hint

Remove the ! symbol to run this command in your terminal. But keep it if you run this cell into a Jupyter notebook.

!juice-agm --help

/home/docs/checkouts/readthedocs.org/user_builds/esa-ptr/envs/latest/bin/juice-agm:3: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr.cli import cli_juice_agm
usage: juice-agm [-h] [--mk METAKERNEL] [--endpoint URL] [--quaternions]
                 [--ck FILENAME] [--ptr-resolved FILENAME] [--log]
                 [--no-cache] [--show-contexts]
                 [ptr]

Check ESA/JUICE PTR validity with AGM.

positional arguments:
  ptr                   PTR/PTX input file.

optional arguments:
  -h, --help            show this help message and exit
  --mk METAKERNEL       Metakernel to use with AGM (default: "JUICE CREMA 5.1
                        150lb_23_1").
  --endpoint URL        AGM API endpoint URL (default: `JUICE_API`).
  --quaternions         Display computed quaternions (optional).
  --ck FILENAME         CK output filename (optional).
  --ptr-resolved FILENAME
                        Resolved PTR output filename (optional).
  --log                 Display AGM log (optional).
  --no-cache            Disable cache (optional).
  --show-contexts       Show available metakernel contexts.

By default, the tool will use JUICE pointing tool as AGM API endpoint. In the future, it should be possible use locally hosted AGM instances to perform complex queries.

If you just need to test the validity of a ptr file you just have to do:

!juice-agm example.ptx

/home/docs/checkouts/readthedocs.org/user_builds/esa-ptr/envs/latest/bin/juice-agm:3: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr.cli import cli_juice_agm

AGM simulation: Success

You can explicitly say with which metakernel you want to work with:

!juice-agm --mk "JUICE CREMA 5.1 150lb_23_1" example.ptx

/home/docs/checkouts/readthedocs.org/user_builds/esa-ptr/envs/latest/bin/juice-agm:3: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr.cli import cli_juice_agm

AGM simulation: Success

If you are only interested by the quaternions, you can request them:

!juice-agm --quaternions example.ptx

/home/docs/checkouts/readthedocs.org/user_builds/esa-ptr/envs/latest/bin/juice-agm:3: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr.cli import cli_juice_agm

AGM simulation: Success
Quaternions:

You can also save the generated CK file or/and resolved ptr file locally:

!juice-agm --ck example.ck --ptr-resolved agm_resolved.ptx example.ptx

/home/docs/checkouts/readthedocs.org/user_builds/esa-ptr/envs/latest/bin/juice-agm:3: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr.cli import cli_juice_agm

AGM simulation: Success

AGM CK saved in `example.ck`.

AGM resolved PTR saved in `agm_resolved.ptx`.

You can also get the different metakernels context available on the Juice pointing api like this:

!juice-agm --show-contexts

/home/docs/checkouts/readthedocs.org/user_builds/esa-ptr/envs/latest/bin/juice-agm:3: Warning: ESA-PTR is depreciated, use PTR-EDITOR instead.
  from ptr.cli import cli_juice_agm

JUICE_API metakernel contexts available:
- JUICE Planning Cruise
- JUICE Planning
- JUICE CREMA 5.1 150lb_23_1_b2
- JUICE CREMA 5.1 150lb_23_1_a3
- JUICE CREMA 5.1 150lb_23_1
- JUICE CREMA 5.0