Skip to content

01 ‐ How To Use

Jump to bottom Edit New page
Andrea Pizzetti edited this page Jun 16, 2026 · 3 revisions

Initialization

To install ABRAM for the first time, run the following command in MATLAB:

abram_install()

from the folder where you cloned the repository. From now on, you can call this same function from everywhere in your system and the required paths will be added to the MATLAB path.

Architecture & Interface

The tool architecture is object-oriented and is based on a render object that is used as rendering agent and main container and manipulator of data for each rendering session. The input data is provided by the user with YML files. The user interfaces with the rendering agent by modifying its properties and calling the rendering method to generate a new rendering every time a property is modified.

To initialize the rendering agent, the render() method is called:

rend = abram.render()

The same method can also be called with the filepath of an input configuration file to generate the first rendering:

rend = abram.render('YOUR_FILE.YML')

To generate new renderings, the rend properties can be modified with the desired parameters (for instance, new pose or new camera properties), then the rendering method is called to generate a new rendering:

rend = rend.rendering()

It is suggested to use the rend object in this way to skip most of the pre-processing activities and lower the computational times. Note that multiple objects can be generated and treated as separate entities.

YML Input File Structure

A single YML file is used as main configuration file. The YML file is read by the rendering agent at runtime, which carry out all the required loading and pre-processing activities. The YML file contains information on the scene, the geometry, the user settings, and the pointers to external data such as texture maps.

An overview of the structure of the configuration file and its possible entries is shown in the following. Many fields can be omitted when in doubt. Note that the SI units are always used (meters).

light

  • radius: Light radius in meters [m].
    • Example: 6.95E8
  • type: Light type. Choose one among:
    • bb: Black-body spectrum emission, use the ideal spectrum of a black body at the given temperature. Ideal for stars.
    • sun: Use the Sun tabulated emission spectrum, provided it was downloaded from https://rredc.nrel.gov/solar/spectra/am0/.
    • spectrum: Provide your own radiance spectrum.
  • temperature: Light temperature in Kelvin [K]. Used when type = bb.
    • Example: 5782.0
  • radiance: Light radiance spectrum. Used when type = spectrum. Characterized by:
    • lambda_min: array of wavelength band lower limits in meters [m].
    • lambda_max: array of wavelength band upper limits in meters [m].
    • values: light radiance integrated in each band [W/m^2/sr].

body

  • radius: Body radius in meters [m]. If ellipsoid, provide radii as 2 (semi-major axis and semi-minor axis) or 3 (semi-major axis, intermediate axis and semi-minor axis) elements vector.
    • Example: 1737400.0
  • albedo: The uniform albedo of the body, dimensionless. This value is ignored when an albedo map is present.
    • Example: 0.12
  • albedo_type: Type of albedo used in the computations. It refers to the uniform albedo or to the albedo provided in the albedo map. Choose one among:
    • bond
    • geometric
    • normal
  • maps: Collection of optional texture maps. For each map the filepath and the bit depth must be provided. For each map some optional parameters such as the scale, the mean, the shift, the frame can be provided. More details in Texture Maps.
    • albedo: this map provides the local albedo value of the surface. the albedo is of the type defined by the albedo_type field.
      • Example: {filename: moon/lroc_cgi/lroc_color_poles_2k.tif, depth: 8.0, mean: 0.12}
    • displacement: this map provides the local displacement value with respect to the reference sphere.
      • Example: {filename: moon/ldem_4.tif, depth: 1, scale: 1000.0}
    • normal: this map provides the local orientation of the surface in body-fixed or local topographic frame.
      • Example: {filename: moon/Moon_LRO_LOLA_NBM_Global_4ppd_pizzetti2025.tif, depth: 32.0, frame: body}
    • horizon: this map provides the critical elevation under which the occlusion check is performed for each point on the surface.
      • Example: {filename: moon/Moon_LRO_LOLA_HM_Global_4ppd_pizzetti2025.tif, depth: 1}
    • radiance: this map provides an emission radiance on the body surface that is integrated and collected by the camera.
      • Example: {filename: earth/Earth_Radiance_Global_75ppd_pizzetti2025.tif, depth: 8.0, scale: 1}
  • radiometry: Defines the reflection model of the body's surface. Choose one among:
    • lambert: Lambertian reflection.
    • lommel: Lommel-Seeliger reflection.
    • area: Area reflection.
    • oren: Oren-Nayar reflection, for rough surfaces; requires roughness parameter.
    • specular: Specular reflection, for shiny surfaces; requires shininess parameter.
    • phong: Phong reflection model, blending Lambert and Specular; requires shininess, weight_lambert, and weight_specular parameters.
    • hapke: Hapke reflection model, suited for the Moon surface; requires parameters array [b_HG, c_HG, B0_CBOE, h_CBOE, B0_SHOE, h_SHOE, roughness, filling_factor].

camera

  • exposure_time: Exposure duration in seconds [s].
  • focal_length: Lens focal length in meters [m].
  • f_number: F-stop number, dimensionless.
  • pixel_width: Pixel size in meters [m].
  • resolution: Array of two values representing horizontal and vertical resolution in pixels [px].
  • full_well_capacity: Maximum charge capacity of a pixel in electrons [e-].
  • gain_analog2digital: Analog to digital conversion gain [DN/e-].
  • amplification: Digital amplification in decibels [dB].
  • offset: Image offset in digital number [DN].
  • quantum_efficiency: Detector quantum efficiency characterized by:
    • lambda_min: array of wavelength band lower limits in meters [m]
    • lambda_max: array of wavelength band upper limits in meters [m]
    • values: efficiency values for each band, dimensionless.
    • sampling: piecewise or midpoint method for sampling.
  • transmittance: Optical transmittance of the detector characterized by similar arrays and sampling methods as quantum_efficiency.
  • noise: Noise characteristics:
    • aberration: Aberrations with flag, Zernike coefficients as RMS of diffraction wave (tiltX, tiltY, defocus, astig45, astig0, comaY, comaX, trefoilY, trefoilX), and polychromatic flag (to compute a different PSF for each camera waveband).
    • blooming: Blooming noise with flag, diffusion coefficients (alpha and beta) and standard deviation coefficient (sigma).
    • shot: Shot noise model with flag and random number generation seed.
    • dark: Dark current noise model with flag, dark current mean signal [e-/s], standard deviation of the multiplicative factor [-], and random number generation seed.
    • prnu: Photo-Response Non-Uniformity noise model with flag, standard deviation of non-uniformity [-], and random number generation seed.
    • smearing: Smearing noise model with flag, readout time per row [s] and direction ('up' or 'down').
    • readout: Readout noise with flag, standard deviation [e-], and random number generation seed.
  • distortion: Optical distortion parameters according to the Brown distortion model:
    • radial: Radial distortion coefficients (k1, k2 and k3).
    • decentering: Tangential distortion coefficients (p1 and p2).

scene

The geometry of the scene can be provided with either one of two sets of parameters using different frames. The frames and conventions used in ABRAM are defined in Frames & Conventions. The first set of parameters is composed of:

  • d_body2light: Distance between body and light in meters.
  • d_body2cam: Distance between body and camera in meters.
  • phase_angle: Phase angle in radians.
  • rpy_CAMI2CAM: Attitude angles (roll, pitch, yaw) of Camera frame relative to Camera Ideal frame in radians; list format.
  • rpy_CSF2IAU: Attitude angles of Camera-target-Sun frame relative to International Astronomical Union frame in radians; list format.

This set allows you to play easily with the geometry, as you can rotate the camera frame (CAM) with respect to an ideal orientation that points to the body (CAMI), or rotate the body texture (IAU) with respect to an ideal orientation that points to the light (CSF). You can also change phase angle and distances between body and light independently.

The second set is composed of:

  • pos_body2light_IAU: Position between body and light in IAU frame in meters.
  • pos_body2cam_IAU: Distance between body and camera in IAU frame in meters.
  • q_IAU2CAM: Quaternion of CAM relative to IAU, scalar-first convention; list format.

This set is suggested when you already have a trajectory defined in the body-fixed IAU frame. ABRAM will deal internally with all the required transformations. If your trajectory is defined in ECI, convert it to the body-fixed IAU frame of the target body first.

setting

All the setting fields are optional. In most cases, the ABRAM default settings should work fine for your application, and you don't need to touch them. Modify them to change render engine behaviour and trade off between accuracy and performance.

  • saving
    • filename: string. Filename without extension of the saved image file.
    • format: 'png', 'jpeg' or 'tif'. Format of the saved image file. Tif is required for hyperspectral images.
    • depth: 8, 16 or 32. Bit depth for the saved image file.
    • color: 'mono' or 'multi'. Monochromatic or hyperspectral image.
  • general
    • parallelization: boolean flag. Used for multithreading, false for single-thread. Default is true.
    • workers: integer. Specify the number of workers/threads. Default is 'auto' and use the maximum number for your machine.
    • nmax: integer. Specify the maximum number of elements for an array to avoid memory issues. Default is 100 millions.
    • verbose: boolean flag. Print the ABRAM rendering log. Default is true.
  • discretization
    • method: 'fixed' or 'adaptive'. Decision logic for the number of discretization points of the body.
    • (if method == 'fixed') np: scalar. Number of discretization points.
    • (if method == 'adaptive') accuracy: 'high', 'medium', 'low' or scalar. Number of points for each active pixel of the camera.
  • sampling
    • method: 'uniform', 'projecteduniform', 'concentrated' or 'auto'. Default is 'auto', which use 'concentrated' at close-range, 'uniform' when sampling limits are specified, 'projecteduniform' otherwise.
    • limits: 'fixed' or 'auto'. Decision logic for the sampling limits. If 'fixed', specify the limits in body.lon_lims and body.lat_lims as longitude and latitude in CSF frame in radians.
    • intersect_fov: boolean flag. Run a FOV intersection algorithm to reduce sampling space.
  • culling
    • occlusion_method: 'raytracing' or 'depthbuffer'. Method for shadows culling.
    • occlusion_algorithm: 'sampling' or 'iterative'. Use fixed sampling or ray-marching for raytracing method.
    • occlusion_rays: scalar or 'auto'. Number of rays step or samples.
    • occlusion_angle: scalar or 'auto'. Angular extension of rays.
    • occlusion_accuracy: scalar or 'auto'. Threshold for considering a ray hit.
    • outrange_threshold: scalar. Threshold for non-renderizable points expressed as a multiplier of the closest range' point. Default is 100.
    • impact_threshold: scalar. Threshold for impact against body surface expressed as a percentage of body radius. Default is 5 meters for the Moon scenario.
  • integration
    • method: 'integral', 'trapz', or 'constant'. Method for radiometry integration.
    • (if method== 'trapz') np: scalar. Number of trapezoidal integration points, default is 10.
    • soft_shadows: scalar. Amount of soft shadowing, from 0 to 1. Default is 0.
  • gridding
    • method: 'sum' or 'weightedsum'. Direct gridding method
    • (if method == 'weightedsum') algorithm: 'area', 'diff', 'invsquared', or 'gaussian'. Kernel for gridding of continuous data into pixel array.
    • (if algorithm== 'gaussian') gamma: scalar. Standard deviation of the Gaussian gridding kernel. Reduce for a crispier image but a larger probability of artifacts.
  • reconstruction
    • granularity: scalar or auto. To specify super-sampling of the pixel array before direct gridding.
    • filter: nearest, bilinear, bicubic, lanczos2, lanczos3, gaussian, osculatory. Reconstruction interpolating filter for granularity values larger than 1.
    • antialiasing: boolean flag. To suppress aliasing when downsampling the image. Used for granularity values larger than 1.

Output Object File Structure

The rend object contains the output of the rendering in terms of adimensionalized 3D Point Cloud (cloud), radiance hyperspectral array (matrix with Nb channels), Electron Count Rate array (ecr), electron count array (ec), noise matrices (noise), final image in double format (img), and adimensional depth map (depth):

        cloud: [1×1 struct]
     radiance: [1024×1024xNb double]
          ecr: [1024×1024 double]
           ec: [1024×1024 double]
          img: [1024×1024 double]
        noise: [1×1 struct]
        depth: [1×1 struct]

The rend object also contains some post-processed useful data such as the horizontal and vertical ground sampling distance at nadir (gsd), the body dimension in angular and pixel unit of measures (bodyAngSize, bodyPxSize), the center of the body projected on the image (bodyPxCenter), the matrix and vector of the conic coefficients (conicMat, conicVec).

          gsd: [1x2 double]
  bodyAngSize: [1 double]
   bodyPxSize: [1x2 double]
 bodyPxCenter: [2×1 double]
     conicMat: [3×3 double]
     conicVec: [1x6 double]

Finally, inside the rend object also the original input data is stored:

         light: [1×1 abram.star]
         body: [1×1 abram.body]
       camera: [1×1 abram.camera]
        scene: [1×1 abram.scene]
      setting: [1×1 abram.setting]

which can be modified directly by accessing the fields of the nested objects in order to generate a new rendering with different data.

Add a custom footer
Add a custom sidebar

Clone this wiki locally