`shape`¶

This module contains a set of factory functions for setting up the physical shape of natural bodies in an environment.

The main interfaces with Tudat is the shape_settings attribute (of type BodyShapeSettings) of the body settings, which defines settings for the shape model of a body. The functions in this submodule are used to create these settings objects. When creating a body (typically using the create_system_of_bodies() function), an object of type BodyShapeModel (or a derived class) is created and added to the associated Body object based on the settings object, which can be retrieved using the shape_model attribute.

The following code block gives an overview of the steps to define, create, and extract a shape model, for the specific example of an oblate spheroid shape model: with \(R_{e}=3396.2\) km equatorial radius, and flattening \(f=0.00589\)

from tudatpy.dynamics import environment_setup
from tudatpy.astro import time_representation

# Create body settings
body_settings =  environment_setup.get_default_body_settings( ... ) # Typical way to instantiate body settings

# Modify shape model settings (base class type BodyShapeSettings)
body_settings.get( 'Mars' ).shape_settings = environment_setup.shape.oblate_spherical(
    equatorial_radius = 3396.2E3,
    flattening = 0.00589 )

# Create bodies
bodies = environment_setup.create_system_of_bodies(body_settings)

# Extract shape model (base class type ShapeModel) from Earth
mars_shape_model = bodies.get( 'Mars' ).shape_model

Note that, in Tudat, the physical shape of a body and its gravity field are completely independent. In addition, the functionality in this module is for defining shapes of natural bodies. Shapes of spacecraft (e.g. macromodels) are defined through functionality in the vehicle_systems() module.

Functions¶

`spherical`(radius)	Function for creating spherical body shape model settings.
`spherical_spice`()	Function for creating spherical body shape model settings entirely from spice.
`oblate_spherical`(equatorial_radius, flattening)	Function for creating oblate spherical body shape model settings.
`oblate_spherical_spice`()	Function for creating oblate spherical body shape model settings entirely from spice.
`polyhedron`(vertices_coordinates, ...[, ...])	Function for creating a polyhedron body shape model settings.
`hybrid`(low_resolution_body_shape_settings, ...)	Function for creating hybrid body shape model settings.

spherical(radius: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings¶

Function for creating spherical body shape model settings.

Function for settings object, defining strictly spherical body shape model entirely from single radius parameter.

Parameters:: radius (float) – Radius specifying spherical body shape.
Returns:: Instance of the BodyShapeSettings derived SphericalBodyShapeSettings class
Return type:: SphericalBodyShapeSettings

Examples

In this example, we create a BodyShapeSettings using a perfectly spherical shape model:

# define parameters describing perfectly spherical model
body_radius = 6378.0E3
# create shape model settings
body_settings.get( "Earth" ).shape_settings = environment_setup.shape.spherical( body_radius )

spherical_spice() → tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings¶

Function for creating spherical body shape model settings entirely from spice.

Function for settings object, defining spherical body shape model entirely from spice parameters.

Returns:: Instance of BodyShapeSettings class
Return type:: BodyShapeSettings

Examples

In this example, we create a BodyShapeSettings using a perfectly spherical shape model and data from Spice:

# create shape model settings
body_settings.get( "Earth" ).shape_settings = environment_setup.shape.spherical_spice( )

oblate_spherical(equatorial_radius: float | SupportsIndex, flattening: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings¶

Function for creating oblate spherical body shape model settings.

Function for settings object, defining oblate spherical body shape model from equatorial radius and flattening parameter.

Parameters:

equatorial_radius (float) – Equatorial radius specifying oblate spherical body shape.
flattening (float) – Flattening parameter specifying oblate spherical body shape.

Returns:

Instance of the BodyShapeSettings derived OblateSphericalBodyShapeSettings class

Return type:

OblateSphericalBodyShapeSettings

Examples

In this example, we create a BodyShapeSettings using a perfectly oblate spherical shape model:

# define parameters describing oblate spherical model
body_radius = 6378.0E3
body_flattening = 1.0 / 300.0
# create shape model settings
body_settings.get( "Earth" ).shape_settings = environment_setup.shape.oblate_spherical( body_radius, body_flattening )

oblate_spherical_spice() → tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings¶: Function for creating oblate spherical body shape model settings entirely from spice. :returns: Instance of BodyShapeSettings class :rtype: BodyShapeSettings

polyhedron(vertices_coordinates: numpy.ndarray[numpy.float64[m, n]], vertices_defining_each_facet: numpy.ndarray[numpy.int32[m, n]], compute_altitude_with_sign: bool = True, just_compute_distance_to_vertices: bool = False) → tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings¶

Function for creating a polyhedron body shape model settings.

Function for settings object, defining a polyhedron shape model.

Note 1: The evaluation of the altitude with a polyhedron model tends to be computationally expensive. To reduce the computational time, it might be useful to instead define a hybrid shape model (see hybrid()), which allows using a high-resolution polyhedron (with a large number of facets) at low altitudes and a low-resolution one (with smaller number of facets) at high-altitudes.

Note 2: If the goal of using the shape model is only to detect collisions with the surface and not to explicitly obtain the altitude, it is instead recommended to use the Laplacian of the gravitational potential (see gravity_field_laplacian_of_potential()). This allows reducing the computational time, but is only valid if the same polyhedron model that is used to define the gravitational acceleration should also be used to detect the impacts.

Parameters:

vertices_coordinates (numpy.ndarray) – Cartesian coordinates of each polyhedron vertex. Entry (i,j) denotes vertex i, coordinate j (one row per vertex, 3 columns).
vertices_defining_each_facet (numpy.ndarray) – Index (0 based) of the vertices constituting each facet. Entry (i,j) denotes facet i, and the jth vertex of the facet (one row per facet, 3 columns). In each row, the vertices’ indices should be ordered counterclockwise when seen from the outside of the polyhedron.
compute_altitude_with_sign (bool, default=True) – Flag indicating whether the altitude should be computed with sign (i.e. >0 if above surface, <0 otherwise) or having always a positive value. If the the sign of the altitude is not relevant, then setting it to false is recommended, as it reduces the CPU time.
just_compute_distance_to_vertices (bool, default=False) – Flag indicating whether the altitude should be computed just with respect to the polyhedron vertices (if flag is set to true) or to all polyhedron features (vertices, facets and edges; happens if flag is set to false). Depending on the application, it might be useful to set the flag to true for medium to high altitudes, as it allows significantly reducing the CPU time (the resulting altitude errors depend on the resolution of the used polyhedron and altitude itself).

Returns:

Instance of the BodyShapeSettings derived PolyhedronBodyShapeSettings class

Return type:

PolyhedronBodyShapeSettings

hybrid(low_resolution_body_shape_settings: tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings, high_resolution_body_shape_settings: tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings, switchover_altitude: float | SupportsIndex) → tudatpy.kernel.dynamics.environment_setup.shape.BodyShapeSettings¶

Function for creating hybrid body shape model settings.

Function for settings object, defining a hybrid shape model.

The hybrid shape model is constituted by two shape models: a low-resolution model which is used at high altitudes (above the switchover altitude) and a high-resolution model used at low altitudes (below the switchover altitude). In each computation of the altitude, the altitude is first computed with the low-resolution model. The low-resolution altitude is then compared to the switchover altitude to decide whether to compute the high-resolution altitude.

The hybrid shape model is useful when the evaluation of the high-resolution model is computationally expensive (e.g. polyhedron model).

Parameters:

low_resolution_body_shape_settings (BodyShapeSettings) – Settings of the shape model that is to be used to compute the altitude at high altitudes (above the switchover altitude).
high_resolution_body_shape_settings (BodyShapeSettings) – Settings of the shape model that is to be used to compute the altitude at low altitudes (below the switchover altitude).
switchover_altitude (float) – Altitude at which the model used to compute the altitude is changed. The high-resolution model is used for altitudes below the switchover altitude, the low-resolution model for altitudes above it.

Returns:

Instance of the BodyShapeSettings derived HybridBodyShapeSettings class

Return type:

HybridBodyShapeSettings

Classes¶

`BodyShapeSettings`	Base class for providing settings for body shape model.
`SphericalBodyShapeSettings`	Class for defining model settings of a strictly spherical body shape.
`OblateSphericalBodyShapeSettings`	Class for defining model settings of a oblate spherical body shape.
`PolyhedronBodyShapeSettings`	Class for defining model settings of a polyhedron body shape.
`HybridBodyShapeSettings`	Class for defining model settings of a hybrid body shape.

class BodyShapeSettings¶

Bases: pybind11_object

Base class for providing settings for body shape model.

Functional (base) class for settings of body shape models that require no information in addition to their type. Body shape model settings requiring additional information must be defined using an object derived from this class.

class SphericalBodyShapeSettings¶

Bases: BodyShapeSettings

Class for defining model settings of a strictly spherical body shape.

BodyShapeSettings derived class for strictly spherical body shape model settings.

property radius¶

read-only

Radius specifying spherical body shape.

Type:: float

class OblateSphericalBodyShapeSettings¶

Bases: BodyShapeSettings

Class for defining model settings of a oblate spherical body shape.

BodyShapeSettings derived class for oblate spherical body shape model settings.

property equatorial_radius¶

read-only

Equatorial radius of the oblate spherical body shape.

Type:: float

property flattening¶

read-only

Flattening of spheroid shape model.

Type:: float

class PolyhedronBodyShapeSettings¶

Bases: BodyShapeSettings

Class for defining model settings of a polyhedron body shape.

BodyShapeSettings derived class for polyhedron body shape model settings.

property compute_altitude_with_sign¶

Flag indicating whether the altitude should be computed with sign (i.e. >0 if above surface, <0 otherwise) or having always a positive value. If the the sign of the altitude is not relevant, then setting it to false is recommended, as it reduces the CPU time for computing the altitude.

Type:: bool, default=True

property just_compute_distance_to_vertices¶

Flag indicating whether the altitude should be computed just with respect to the polyhedron vertices (if flag is set to true) or to all polyhedron features (vertices, facets and edges; happens if flag is set to false). Depending on the application, it might be useful to set the flag to true for medium to high altitudes, as it allows significantly reducing the CPU time (the resulting altitude errors depend on the resolution of the used polyhedron and altitude itself).

Type:: bool, default=False

property vertices_coordinates¶

Cartesian coordinates of each polyhedron vertex. Entry (i,j) denotes vertex i, coordinate j (one row per vertex, 3 columns).

Type:: numpy.ndarray

property vertices_defining_each_facet¶

Index (0 based) of the vertices constituting each facet. Entry (i,j) denotes facet i, and the jth vertex of the facet (one row per facet, 3 columns). In each row, the vertices’ indices should be ordered counterclockwise when seen from the outside of the polyhedron.

Type:: numpy.ndarray

class HybridBodyShapeSettings¶

Bases: BodyShapeSettings

Class for defining model settings of a hybrid body shape.

BodyShapeSettings derived class for hybrid body shape model settings.

property high_resolution_body_shape_settings¶: No documentation found.

property low_resolution_body_shape_settings¶: No documentation found.

property switchover_altitude¶: No documentation found.

shape¶

Functions¶

Classes¶

`shape`¶