satsim package — SatSim 0.13.0 documentation

# satsim package

Top-level package for SatSim.

## Subpackages

- satsim.dataset package
  - Submodules
  - satsim.dataset.augment module
    - `augment_satnet_with_satsim()`
- satsim.generator package
  - Subpackages
    - satsim.generator.obs package
      - Submodules
      - satsim.generator.obs.breakup module
      - satsim.generator.obs.cso module
      - satsim.generator.obs.geometry module
      - satsim.generator.obs.io module
      - satsim.generator.obs.rpo module
- satsim.geometry package
  - Submodules
  - satsim.geometry.astrometric module
    - `GreatCircle`
    - `angle_between()`
    - `angle_from_los()`
    - `apparent()`
    - `create_topocentric()`
    - `gen_track()`
    - `gen_track_from_wcs()`
    - `get_los()`
    - `get_los_azel()`
    - `lambertian_sphere_to_mv()`
    - `load_earth()`
    - `load_moon()`
    - `load_sun()`
    - `query_by_los()`
    - `wcs_from_observer_fixed()`
    - `wcs_from_observer_rate()`
    - `wcs_from_observer_sidereal()`
  - satsim.geometry.csvsc module
    - `query_by_los()`
  - satsim.geometry.draw module
    - `gen_curve_from_points()`
    - `gen_line()`
    - `gen_line_from_endpoints()`
  - satsim.geometry.ephemeris module
    - `EphemerisObject`
      - `EphemerisObject.center`
    - `create_ephemeris_object()`
  - satsim.geometry.random module
    - `gen_random_points()`
  - satsim.geometry.sgp4 module
    - `create_sgp4()`
    - `load_tle()`
  - satsim.geometry.sprite module
    - `load_sprite_from_file()`
  - satsim.geometry.sstr7 module
    - `get_star_mv()`
    - `load_index()`
    - `load_stars_for_zone()`
    - `load_zone()`
    - `query_by_los()`
    - `query_by_min_max()`
    - `read_star()`
    - `select_zone()`
  - satsim.geometry.transform module
    - `apply_wrap_around()`
    - `rotate_and_translate()`
  - satsim.geometry.twobody module
    - `EarthTwoBodySatellite`
      - `EarthTwoBodySatellite.center`
    - `create_twobody()`
    - `create_twobody_from_tle()`
  - satsim.geometry.wcs module
    - `get_min_max_ra_dec()`
    - `get_wcs()`
- satsim.image package
  - Submodules
  - satsim.image.augment module
    - `crop_and_resize()`
    - `flip()`
    - `load_from_file()`
    - `null()`
    - `pow()`
    - `resize()`
    - `rotate()`
    - `scatter_shift()`
    - `scatter_shift_polar()`
    - `scatter_shift_random()`
  - satsim.image.fpa module
    - `add_counts()`
    - `add_patch()`
    - `analog_to_digital()`
    - `crop()`
    - `downsample()`
    - `mv_to_pe()`
    - `pe_to_mv()`
    - `transform_and_add_counts()`
    - `transform_and_fft()`
  - satsim.image.model module
    - `astropy_model2d()`
    - `polygrid2d()`
    - `radial_cos2d()`
    - `sin2d()`
  - satsim.image.noise module
    - `add_photon_noise()`
    - `add_read_noise()`
  - satsim.image.psf module
    - `eod_to_sigma()`
    - `gen_from_poppy()`
    - `gen_from_poppy_configuration()`
    - `gen_gaussian()`
  - satsim.image.render module
    - `render_full()`
    - `render_piecewise()`
- satsim.io package
  - Submodules
  - satsim.io.czml module
    - `CZMLExtractor`
      - `CZMLExtractor.add_ground_station()`
      - `CZMLExtractor.add_object()`
      - `CZMLExtractor.get_document()`
    - `save_czml()`
  - satsim.io.fits module
    - `save()`
  - satsim.io.image module
    - `save()`
    - `save_apng()`
  - satsim.io.satnet module
    - `init_annotation()`
    - `set_frame_annotation()`
    - `write_frame()`
- satsim.math package
  - Submodules
  - satsim.math.angle module
    - `diff_degrees()`
    - `interp_degrees()`
    - `mean_degrees()`
  - satsim.math.conv module
    - `conv2()`
  - satsim.math.fft module
    - `fftconv2()`
    - `fftconv2p()`
    - `fftshift()`
  - satsim.math.interpolate module
    - `lagrange()`
  - satsim.math.random module
    - `gen_sample()`
    - `gen_samples_from_bins()`
    - `lognormal()`
  - satsim.math.stats module
    - `signal_to_noise_ratio()`
- satsim.pipeline package
  - `constant()`
  - `cos()`
  - `glint()`
  - `poly()`
  - `polyt()`
  - `sin()`
  - `sin_add()`
- satsim.time package
  - `TimeWrapper`
  - `delta_sec()`
  - `from_astropy()`
  - `from_datetime()`
  - `linspace()`
  - `to_astropy()`
  - `to_utc_list()`
  - `utc()`
  - `utc_from_list()`
  - `utc_from_list_or_scalar()`
- satsim.util package
  - Submodules
  - satsim.util.system module
    - `configure_eager()`
    - `configure_multi_gpu()`
    - `configure_single_gpu()`
    - `get_semantic_version()`
  - satsim.util.thread module
    - `MultithreadedTaskQueue`
      - `MultithreadedTaskQueue.has_tag()`
      - `MultithreadedTaskQueue.stop()`
      - `MultithreadedTaskQueue.task()`
      - `MultithreadedTaskQueue.waitUntilEmpty()`
    - `ThreadedTaskQueue`
      - `ThreadedTaskQueue.busy()`
      - `ThreadedTaskQueue.has_tag()`
      - `ThreadedTaskQueue.stop()`
      - `ThreadedTaskQueue.task()`
      - `ThreadedTaskQueue.waitUntilEmpty()`
  - satsim.util.timer module
    - `get_timing()`
    - `tic()`
    - `toc()`

## Submodules

## satsim.cli module

## satsim.config module

satsim.config.dict_merge(dct, merge_dct)

  Recursive dict merge. Inspired by `dict.update()`, instead of updating only top-level keys, dict_merge recurses down into dicts nested to an arbitrary depth, updating keys. The merge_dct is merged into dct.

  Param:

    dct: dict, onto which the merge is executed merge_dct: dict, dct merged into dct

satsim.config.has_key_deep(d, key)

  Nested check to see if a dictionary has a key.

  Parameters:

    - d – dict or list

    - key – str, key name to check for

satsim.config.load_json(filename)

  Opens a JSON file and returns the result as a dictionary.

  Parameters:

    filename – str, path to file

  Returns:

    A dict, the result.

satsim.config.load_yaml(filename)

  Opens a YAML file and returns the result as a dictionary.

  Parameters:

    filename – str, path to file

  Returns:

    A dict, the result.

satsim.config.parse_cache(param)

  Parse a cache parameter. The input argument, param, may contain the following keys and values which describe the function to run. For example:

      param = {
          '$cache': './path/to/cache'
      }

  Cache is not used if $cache key is not present.

  Parameters:

    param – dict, a dictionary that contain keys: $cache

  Returns:

    A tuple,

      a dictionary, loaded from cache if available a boolean, True if cache loaded, False otherwise

satsim.config.parse_function(param)

  Parse a function. The input argument, param, should contain the following keys and values which describe the function to run. For example:

      param = {
          'module': 'my_module',
          'function': 'my_function',
          'kwargs': { 'param_1': 10.0, 'param_2': 'astring' }
      }

  Which is comparable to:

      import my_module
      return lambda: my_function(param_1 = 10.0, param_2 = 'astring')

  Parameters:

    param – dict, a dictionary that contain keys: module, function, kwargs

  Returns:

    A function, a lambda function encapsulating the parsed function and

      arguments

satsim.config.parse_function_pipeline(param)

  Parse a pipeline of functions. See parse_function.

  Parameters:

    param – dict, a dictionary that contain keys: module, function, kwargs

  Returns:

    An func, a function encapsulating the pipeline

satsim.config.parse_generator(param)

  Parse and run a generator function. See parse_function.

  Parameters:

    param – dict, a dictionary that contain keys: module, function, kwargs

  Returns:

    A dict, a dictionary generated by the generator function

satsim.config.parse_import(param)

  Parse a import key. The input argument, param, should contain the following keys and values which describe the function to run. For example:

      param = {
          '$import': './base.json',
          'override': { 'param_1': 10.0, 'param_2': 'override string' }
      }

  Parameters:

    param – dict, a dictionary that contain keys: import, and optionally override

  Returns:

    A dict, a dictionary generated by the generator function

satsim.config.parse_param(param, dirname=None, run_generator=False, eval_python=False, run_compound=False)

  Parses a parameter and recursively parses any children parameters.

  - if the parameter contains the key sample, result from parse_random_sample will be returned.

  - if the parameter contains the key file, the contents of the loaded pickle file will be returned.

  - if the parameter contains the key generator, result from parse_generator will be returned.

  - else if no special keys are found, param is returned.

  Parameters:

    - param – dict, root parameter

    - dirname – str, root directory for files referenced in param

    - run_generator – boolean, evaluate generator functions during this pass

  Returns:

    A any, a random sample, contents of pickle file, or original value

satsim.config.parse_random_sample(param)

  Parses a random sample parameter and returns a sample. The value of the key $sample should be the format random.DISTRIBUTION, where DISTRIBUTION is a NumPy random distribution. For example:

      p = { "$sample": "random.uniform", "low": 5.0, "high": 22.0 }
      x = parse_random_sample(p)
      # x is a value between 5 and 22

  If the key $sample is equal to random.choice, one option will be chosen from the key choices. For example:

      p = { "$sample": "random.choice", "choices": [1, 2, 4, 8] }
      x = parse_random_sample(p)
      # x will be 1, 2, 4, or 8

  If the key $sample is equal to random.list, a list of random samples will be generated. For example:

      p = {
          "$sample": "random.list",
          "length": 5,
          "value": { "$sample": "random.randint", "low": 0, "high": 10 }
      }
      x = parse_random_sample(p)
      # x will a list of length 5, i.e. x == [7,5,8,5,1]

  Parameters:

    param – dict, random sample parameter

  Returns:

    A number, random sample

satsim.config.save_cache(param, value)

  Saves a parameter to the disk cache. Parameter will be loaded from cache on any subsequent calls.

  Parameters:

    - param – dict, root parameter to be used as the cache key

    - value – any, the value to save to cache

satsim.config.save_debug(configs, output_dir)

  Writes an array of configs to files for debugging.

  Parameters:

    - configs – array, configuration stages output by transform

    - output_dir – str, directory to output files

satsim.config.save_json(filename, config, save_pickle=False)

  Saves a configuration to a JSON file. Any items that are not JSON serializable are saved to a binary pickle file and saved in the same directory as the file filename.

  Parameters:

    - filename – str, path to file

    - config – dict, configuration as a dictionary

satsim.config.transform(config, dirname=None, max_stages=5, with_debug=False, max_imports=20, max_ref=5)

  Transforms a SatSim configuration, evaluating any random sample parameters, references and/or generator functions. The transformation will happen in two passes. The first pass evaluates sample parameters; the second pass evaluates generator parameters. This is repeated for max_stages or until no more generator or sample keys are found.

  Parameters:

    - config – dict, configuration as a dictionary.

    - dirname – str, root directory for files referenced in config.

    - max_stages – int, maximum number of times to evaluate (one stage is equivalent to running pass 1 and pass 2 once each).

    - with_debug – boolean, return config after each stage.

    - max_imports – int, maximum number of times to evaluate imports.

    - max_refs – int, maximum number of times to evaluate refs.

  Returns:

    A dict or tuple,
      if with_debug is False:

        dict, in place transformation of config

      if with_debug is True:

        config: dict, in place transformation of config stages: array, array of dictionaries after each transformation stage

## satsim.satsim module

satsim.satsim.gen_images(ssp, eager=True, output_dir='./', sample_num=0, output_debug=False, queue=None, set_name=None)

  Generates a single set of images.

  Examples:

      # load a template json file
      ssp = load_json('input/config.json')
      ssp = transform(copy.deepcopy(ssp), 'input/')

      # generate SatNet files to the output directory
      gen_images(ssp, eager=True, output_dir='output/')

  Parameters:

    - ssp – dict, static satsim configuration and parameters. Any dynamic parameters should already be transformed.

    - eager – boolean, Has no effect. True only.

    - output_dir – str, output directory to save SatNet files.

    - sample_num – int, recorded to annotation files.

    - output_debug – boolean, output intermediate debug files.

    - queue – MultithreadedTaskQueue, if not None, files will be written.

    - set_name – str, sets the directory name to save the images to, if None, is set to current time.

  Returns:

    A str, directory to where the output files are saved.

satsim.satsim.gen_multi(ssp, eager=True, output_dir='./', input_dir='./', device=None, memory=None, pid=0, output_debug=False)

  Generates multiple sets of images. Number of sets is based on the parameters ssp[‘sim’][‘samples’].

  Examples:

      # load a template json file
      ssp = load_json('input/config.json')

      # edit some parameters
      ssp['sim']['samples'] = 50
      ssp['geometry']['obs']['list']['mv'] = 17.5

      # generate SatNet files to the output directory
      gen_multi(ssp, eager=True, output_dir='output/')

  Parameters:

    - ssp – dict, static or dynamic satsim configuration and parameters.

    - eager – boolean, Has no effect. True only.

    - output_dir – str, output directory to save SatNet files.

    - input_dir – str, typically the input directory of the configuration file.

    - device – array, array of GPU device IDs to enable. If None, enable all.

    - pid – int, an ID to associate this instance to.

    - output_debug – boolean, output intermediate debug files.

satsim.satsim.image_generator(ssp, output_dir='.', output_debug=False, dir_debug='./Debug', with_meta=False, eager=True, num_sets=0)

  Generator function for a single set of images.

  Examples:

      # load a template json file
      ssp = load_json('input/config.json')
      ssp = transform(copy.deepcopy(ssp), 'input/')

      # generate SatNet files to the output directory
      for results in image_generator(ssp, eager=True, output_dir='output/'):
          imshow(results.numpy())

  Parameters:

    - ssp – dict, static satsim configuration and parameters. Any dynamic parameters should already be transformed.

    - output_dir – str, root directory for SatSim configuration file.

    - sample_num – int, recorded to annotation files.

    - output_debug – boolean, output intermediate debug files.

    - dir_debug – str, directory to output debug files.

    - with_meta – boolean, add metadata to the return function.

    - eager – boolean, Has no effect. True only.

    - num_sets – int, number of sets until generator exits. Set to 0 to run forever.

  Returns:

    fpa_digital: image, rendered image. frame_num: int, frame number. astrometrics: dict, astrometry meta data. obs_os_pix: dict, observations meta data. fpa_conv_star: image, pristine image with stars. fpa_conv_targ: image, pristine image with targets. bg_tf: image, background image. dc_tf: image, dark current image. rn_tf: image, read noise image. num_shot_noise_samples: int, number of shot noise samples averaged

  Return type:

    An image, the rendered image. If with_meta is set to True, additional values are returned