rms-starcat 0.0.1__tar.gz → 1.0.0__tar.gz

rms_starcat-1.0.0/.coveragerc

@@ -0,0 +1,3 @@
+[run]
+branch = true
+omit = tests/*

rms_starcat-1.0.0/.flake8

@@ -0,0 +1,6 @@
+[flake8]
+max-line-length: 90
+extend-ignore =
+    # E265 block comment should start with '# '
+    # E266 too many leading '#' for block comment
+    E265, E266

rms_starcat-1.0.0/.github/workflows/run-tests.yml

@@ -0,0 +1,87 @@
+name: Run Tests
+run-name: Run Tests triggered by ${{ github.ref_type }} ${{ github.ref_name }} or ${{ github.triggering_actor }}
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+  schedule:
+    - cron: "21 11 * * 0"
+
+jobs:
+  flake8:
+    name: Lint starcat
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -r requirements.txt
+
+      - name: Flake8
+        run: |
+          flake8 starcat tests
+
+      - name: Mypy
+        run: |
+          mypy starcat tests
+
+  test:
+    name: Test starcat
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+      fail-fast: false
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -r requirements.txt
+
+      # See: https://www.youtube.com/watch?v=ZgVhU5qvK1M
+      # for a walkthrough on how to create the workload_identity_provider
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          project_id: rms-node
+          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
+
+      - name: Test with coverage
+        run: |
+          coverage run -m pytest
+
+      - name: Print coverage report
+        run: |
+          coverage report -m
+
+      - name: Upload coverage report to codecov
+        uses: codecov/codecov-action@v5
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true

rms_starcat-1.0.0/.mypy.ini

@@ -0,0 +1,8 @@
+[mypy]
+strict = True
+
+[mypy-cspyce.*]
+ignore_missing_imports = True
+
+[mypy-starcat._version]
+ignore_missing_imports = True

rms_starcat-1.0.0/.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - requirements: requirements.txt

rms_starcat-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

rms_starcat-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Information for Potential Contributors
+
+First off, thanks for taking the time to contribute!
+
+This software is maintained by the [Ring-Moon Systems Node](https://pds-rings.seti.org) of NASA's [Planetary Data System](https://pds.nasa.gov). All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them; please read the relevant section before making your contribution.
+
+> If you like the project, but just don't have time to contribute, there are other easy ways to support the project and show your appreciation!
+> - Star the project on GitHub
+> - Post about it on social media
+> - Refer to this project in your project's README
+> - Mention the project at conferences and workshops and tell your friends/colleagues
+> - Cite the project in your papers and posters
+
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [I Have a Question](#i-have-a-question)
+- [I Want to Report a Bug](#i-want-to-report-a-bug)
+- [I Want to Suggest an Enhancement](#i-want-to-suggest-an-enhancement)
+- [I Want To Contribute Code](#i-want-to-contribute-code)
+
+
+## Code of Conduct
+
+This project and everyone participating in it are governed by the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code. Please report unacceptable behavior
+to <matt@seti.org>.
+
+
+## I Have a Question
+
+> Please read the available documentation!
+
+Before asking a question, you can search for existing [issues](https://github.com/SETI/rms-starcat/issues) that might help you. If you find a suitable issue and still need clarification, you can write your question in that issue.
+
+If you can't find an appropriate issue and still want to ask a question, we recommend the following:
+
+- Open an [issue](https://github.com/SETI/rms-starcat/issues/new).
+- Provide as much context and detail as you can.
+- Provide project and platform versions (operating system, Python version, etc.), depending on what seems relevant.
+
+We will try to answer your question as soon as possible.
+
+
+## I Want to Report a Bug
+
+### Before Submitting a Bug Report
+
+A good bug report shouldn't leave others needing to chase you for more information. Therefore, we ask you to investigate carefully and collect all appropriate information in advance.
+
+- Make sure that you are using the latest version of this software and its supporting packages.
+- Make sure that you have read the documentation.
+- Determine that your bug really is a bug and not an error in your code or a misunderstanding in how to use our software.
+- To see if other users have experienced (and potentially solved) the same issue you're having, check if there is an existing issue for your bug or error in the [bug tracker](https://github.com/SETI/rms-starcat/issues).
+- Collect information about the bug:
+  - Stack trace (Traceback)
+  - OS and version (Windows/Linux/macOS), processor (x86/ARM/M1), Python version
+  - Detailed information on how to reproduce the bug, including function parameters, command line arguments, and input given/output received.
+
+### How Do I Submit a Good Bug Report?
+
+> You must never report security-related issues, vulnerabilities, or bugs that include sensitive information to the issue tracker or elsewhere in public. Instead, sensitive bugs must be sent by email to <matt@seti.org>.
+
+We use GitHub Issues to track bugs and errors. If you run into an issue with the project:
+
+- Open an [issue](https://github.com/SETI/rms-starcat/issues/new) with a **clear and descriptive title**. Please label the issue as `A-Bug` with no other labels.
+- Explain the **behavior you would expect** and the **behavior observed**.
+- Provide as much context as possible and describe the **detailed steps** that someone can follow to reproduce the problem. This usually includes providing your code; for a good bug report you should isolate the problem and create a reduced test case.
+- Provide other information collected in the previous section, such as the operating system and language version.
+
+Once it's filed:
+
+- The project team will label the issue accordingly.
+- A team member will try to reproduce the issue with your provided steps. If there are no steps given and no obvious way to reproduce the issue, the team will ask you for clarification.
+- If the team is able to reproduce the issue, it will be appropriately labeled and either assigned to a team member to fix, or left unassigned to be [implemented by someone else](#i-want-to-contribute-code).
+
+
+## I Want to Suggest an Enhancement
+
+This section guides you through submitting an enhancement, **including completely new features and minor improvements to existing functionality**.
+
+### Before Submitting an Enhancement
+
+- Make sure that you are using the latest version of this software and its supporting packages.
+- Make sure that you have read the documentation to see if the desired functionality is already provided.
+- Perform a [search](https://github.com/SETI/rms-starcat/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+- Find out whether your idea fits within the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library.
+
+### How Do I Submit a Good Enhancement Suggestion?
+
+We use GitHub Issues to track enhancement requests. If you want to suggest an enhancement:
+
+- Open an [issue](https://github.com/SETI/rms-starcat/issues/new) with a **clear and descriptive title**. Please label the issue as `A-Enhancement` with no other labels.
+- Provide a **detailed** description of the suggested enhancement.
+- **Explain why this enhancement would be useful** to most users.
+
+
+## I Want To Contribute Code
+
+> ### Legal Notice 
+> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content, and that the content you contribute may be provided under the project license.
+
+We welcome all code contributions, including bug fixes, new features, and improvements to documentation.
+
+- All suggested changes must be submitted using GitHub's "Pull Request" functionality.
+- All code changes must include appropriate new or updated tests to verify the changes made.
+- Existing documentation, including function- and file-level docstrings, must be updated as necessary, and new features fully described.
+- Code style must conform to that of the existing code; for Python this is generally a variant of PEP8 and PEP257.
+
+All submissions will be reviewed in detail by a project team member and changes may be suggested. Once the reviewer approves the changes, they will be merged into the main project branch and made a permanent part of the software. Your efforts to improve the software are greatly appreciated!

rms_starcat-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.1
+Name: rms-starcat
+Version: 1.0.0
+Summary: Star catalog database
+Maintainer-email: "Robert S. French" <rfrench@seti.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/SETI/rms-starcat
+Project-URL: Repository, https://github.com/SETI/rms-starcat
+Project-URL: Source, https://github.com/SETI/rms-starcat
+Project-URL: Issues, https://github.com/SETI/rms-starcat/issues
+Keywords: UCAC4,YBSC,star
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Natural Language :: English
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cspyce
+Requires-Dist: numpy
+
+[![GitHub release; latest by date](https://img.shields.io/github/v/release/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/releases)
+[![GitHub Release Date](https://img.shields.io/github/release-date/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/releases)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/SETI/rms-starcat/run-tests.yml?branch=main)](https://github.com/SETI/rms-starcat/actions)
+[![Documentation Status](https://readthedocs.org/projects/rms-starcat/badge/?version=latest)](https://rms-starcat.readthedocs.io/en/latest/?badge=latest)
+[![Code coverage](https://img.shields.io/codecov/c/github/SETI/rms-starcat/main?logo=codecov)](https://codecov.io/gh/SETI/rms-starcat)
+<br />
+[![PyPI - Version](https://img.shields.io/pypi/v/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Format](https://img.shields.io/pypi/format/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rms-starcat)](https://pypi.org/project/rms-starcat)
+<br />
+[![GitHub commits since latest release](https://img.shields.io/github/commits-since/SETI/rms-starcat/latest)](https://github.com/SETI/rms-starcat/commits/main/)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/commits/main/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/commits/main/)
+<br />
+[![Number of GitHub open issues](https://img.shields.io/github/issues-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/issues)
+[![Number of GitHub closed issues](https://img.shields.io/github/issues-closed-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/issues)
+[![Number of GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/pulls)
+[![Number of GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/pulls)
+<br />
+![GitHub License](https://img.shields.io/github/license/SETI/rms-starcat)
+[![Number of GitHub stars](https://img.shields.io/github/stars/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/stargazers)
+![GitHub forks](https://img.shields.io/github/forks/SETI/rms-starcat)
+
+# Introduction
+
+`starcat` is a set of classes for reading and searching star catalogs. Currently NAIF SPICE
+star catalogs, the Yale Bright Star Catalog (YBSC), and UCAC4 are supported.
+
+`starcat` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).
+
+# Installation
+
+The `starcat` module is available via the `rms-starcat` package on PyPI and can be installed with:
+
+```sh
+pip install rms-starcat
+```
+
+# Getting Started
+
+The `starcat` module provides the `StarCatalog` class, which is the superclass for classes
+that handle specific star catalogs. Each star catalog class takes an optional directory
+path to point at the root of the star catalog data; if no directory path is provided,
+the contents of an environment variable is used instead. Each path can be a full URL
+as supported by [`rms-filecache`](https://rms-filecache.readthedocs.io/en/latest/),
+allowing the catalog data to be downloaded (and cached locally) at runtime.
+
+- `SpiceStarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing NAIF SPICE
+    kernels.
+  - Otherwise, the environment variable `SPICE_PATH`, if defined, must contain a `Stars`
+    subdirectory with NAIF SPICE kernels.
+  - Otherwise, the environment variable `OOPS_RESOURCES` must contain a `SPICE/Stars`
+    subdirectory.
+- `YBSCStarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing the file
+    `catalog`.
+  - Otherwise, the environment variable `YBSC_PATH` must point to that directory.
+- `UCAC4StarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing the directory
+    `u4b`.
+  - Otherwise, the environment variable `UCAC4_PATH` must point to that directory.
+
+Each star catalog returns stars as a class that is a subclass of `Star`. Each subclass
+contains the attributes provided by that star catalog, and none are guaranteed to be
+filled in for all stars:
+
+- `SpiceStar`
+- `YBSCStar`
+- `UCAC4Star`
+
+Details of each class are available in the [module documentation](https://rms-starcat.readthedocs.io/en/latest/module.html).
+
+Basic operation is as follows:
+
+```python
+from starcat import YBSCStarCatalog
+import numpy as np
+cat = YBSCStarCatalog()
+ra_vega = 279.2333
+dec_vega = 38.7836
+vega_list = list(cat.find_stars(ra_min=np.radians(ra_vega-0.1),
+                                ra_max=np.radians(ra_vega+0.1),
+                                dec_min=np.radians(dec_vega-0.1),
+                                dec_max=np.radians(dec_vega+0.1)))
+
+assert len(vega_list) == 1
+print(vega_list[0])
+```
+
+yields:
+
+```
+UNIQUE ID 7001 | RA 279.2345833° (18h36m56.300s) | DEC 38.7836111° (+038d47m1.000s)
+VMAG  0.030  | PM RA 259.135 mas/yr  | PM DEC 286.000 mas/yr
+TEMP 10800 | SCLASS A0Va
+Name "3Alp Lyr" | Durch "BD+38 3238" | Draper 172167 | SAO 67174 | FK5 699
+IR 1 Ref NASA | Multiple " " | Aitken 11510 None | Variable "Alp Lyr"
+SCLASS Code   | Galactic LON 67.44 LAT 19.24
+B-V 0.0 | U-B -0.01 | R-I -0.03
+Parallax TRIG 0.1230000 arcsec | RadVel -14.0 km/s V  | RotVel (v sin i) 15.0 km/s
+Double mag diff 10.40 Sep 62.80 arcsec Components AB # 5
+```
+
+# Contributing
+
+Information on contributing to this package can be found in the
+[Contributing Guide](https://github.com/SETI/rms-starcat/blob/main/CONTRIBUTING.md).
+
+# Links
+
+- [Documentation](https://rms-starcat.readthedocs.io)
+- [Repository](https://github.com/SETI/rms-starcat)
+- [Issue tracker](https://github.com/SETI/rms-starcat/issues)
+- [PyPi](https://pypi.org/project/rms-starcat)
+
+# Licensing
+
+This code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-starcat/blob/main/LICENSE).

rms_starcat-1.0.0/README.md

@@ -0,0 +1,120 @@
+[![GitHub release; latest by date](https://img.shields.io/github/v/release/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/releases)
+[![GitHub Release Date](https://img.shields.io/github/release-date/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/releases)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/SETI/rms-starcat/run-tests.yml?branch=main)](https://github.com/SETI/rms-starcat/actions)
+[![Documentation Status](https://readthedocs.org/projects/rms-starcat/badge/?version=latest)](https://rms-starcat.readthedocs.io/en/latest/?badge=latest)
+[![Code coverage](https://img.shields.io/codecov/c/github/SETI/rms-starcat/main?logo=codecov)](https://codecov.io/gh/SETI/rms-starcat)
+<br />
+[![PyPI - Version](https://img.shields.io/pypi/v/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Format](https://img.shields.io/pypi/format/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/rms-starcat)](https://pypi.org/project/rms-starcat)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/rms-starcat)](https://pypi.org/project/rms-starcat)
+<br />
+[![GitHub commits since latest release](https://img.shields.io/github/commits-since/SETI/rms-starcat/latest)](https://github.com/SETI/rms-starcat/commits/main/)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/commits/main/)
+[![GitHub last commit](https://img.shields.io/github/last-commit/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/commits/main/)
+<br />
+[![Number of GitHub open issues](https://img.shields.io/github/issues-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/issues)
+[![Number of GitHub closed issues](https://img.shields.io/github/issues-closed-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/issues)
+[![Number of GitHub open pull requests](https://img.shields.io/github/issues-pr-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/pulls)
+[![Number of GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed-raw/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/pulls)
+<br />
+![GitHub License](https://img.shields.io/github/license/SETI/rms-starcat)
+[![Number of GitHub stars](https://img.shields.io/github/stars/SETI/rms-starcat)](https://github.com/SETI/rms-starcat/stargazers)
+![GitHub forks](https://img.shields.io/github/forks/SETI/rms-starcat)
+
+# Introduction
+
+`starcat` is a set of classes for reading and searching star catalogs. Currently NAIF SPICE
+star catalogs, the Yale Bright Star Catalog (YBSC), and UCAC4 are supported.
+
+`starcat` is a product of the [PDS Ring-Moon Systems Node](https://pds-rings.seti.org).
+
+# Installation
+
+The `starcat` module is available via the `rms-starcat` package on PyPI and can be installed with:
+
+```sh
+pip install rms-starcat
+```
+
+# Getting Started
+
+The `starcat` module provides the `StarCatalog` class, which is the superclass for classes
+that handle specific star catalogs. Each star catalog class takes an optional directory
+path to point at the root of the star catalog data; if no directory path is provided,
+the contents of an environment variable is used instead. Each path can be a full URL
+as supported by [`rms-filecache`](https://rms-filecache.readthedocs.io/en/latest/),
+allowing the catalog data to be downloaded (and cached locally) at runtime.
+
+- `SpiceStarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing NAIF SPICE
+    kernels.
+  - Otherwise, the environment variable `SPICE_PATH`, if defined, must contain a `Stars`
+    subdirectory with NAIF SPICE kernels.
+  - Otherwise, the environment variable `OOPS_RESOURCES` must contain a `SPICE/Stars`
+    subdirectory.
+- `YBSCStarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing the file
+    `catalog`.
+  - Otherwise, the environment variable `YBSC_PATH` must point to that directory.
+- `UCAC4StarCatalog`
+  - The `dir` argument, if specified, must point to a directory containing the directory
+    `u4b`.
+  - Otherwise, the environment variable `UCAC4_PATH` must point to that directory.
+
+Each star catalog returns stars as a class that is a subclass of `Star`. Each subclass
+contains the attributes provided by that star catalog, and none are guaranteed to be
+filled in for all stars:
+
+- `SpiceStar`
+- `YBSCStar`
+- `UCAC4Star`
+
+Details of each class are available in the [module documentation](https://rms-starcat.readthedocs.io/en/latest/module.html).
+
+Basic operation is as follows:
+
+```python
+from starcat import YBSCStarCatalog
+import numpy as np
+cat = YBSCStarCatalog()
+ra_vega = 279.2333
+dec_vega = 38.7836
+vega_list = list(cat.find_stars(ra_min=np.radians(ra_vega-0.1),
+                                ra_max=np.radians(ra_vega+0.1),
+                                dec_min=np.radians(dec_vega-0.1),
+                                dec_max=np.radians(dec_vega+0.1)))
+
+assert len(vega_list) == 1
+print(vega_list[0])
+```
+
+yields:
+
+```
+UNIQUE ID 7001 | RA 279.2345833° (18h36m56.300s) | DEC 38.7836111° (+038d47m1.000s)
+VMAG  0.030  | PM RA 259.135 mas/yr  | PM DEC 286.000 mas/yr
+TEMP 10800 | SCLASS A0Va
+Name "3Alp Lyr" | Durch "BD+38 3238" | Draper 172167 | SAO 67174 | FK5 699
+IR 1 Ref NASA | Multiple " " | Aitken 11510 None | Variable "Alp Lyr"
+SCLASS Code   | Galactic LON 67.44 LAT 19.24
+B-V 0.0 | U-B -0.01 | R-I -0.03
+Parallax TRIG 0.1230000 arcsec | RadVel -14.0 km/s V  | RotVel (v sin i) 15.0 km/s
+Double mag diff 10.40 Sep 62.80 arcsec Components AB # 5
+```
+
+# Contributing
+
+Information on contributing to this package can be found in the
+[Contributing Guide](https://github.com/SETI/rms-starcat/blob/main/CONTRIBUTING.md).
+
+# Links
+
+- [Documentation](https://rms-starcat.readthedocs.io)
+- [Repository](https://github.com/SETI/rms-starcat)
+- [Issue tracker](https://github.com/SETI/rms-starcat/issues)
+- [PyPi](https://pypi.org/project/rms-starcat)
+
+# Licensing
+
+This code is licensed under the [Apache License v2.0](https://github.com/SETI/rms-starcat/blob/main/LICENSE).