This guide provides practical examples for common use cases with the pydeepskylog package.
- Description
- Installation
- Basic Usage
- Magnitude and Sky Brightness Conversions
- Contrast Reserve Calculation
- Optimal Detection Magnification
- DeepskyLog API Integration
- Validation Utilities
- Logging Configuration
- API
- Astronomical Background
- Contributing
- License
- Changelog
- Acknowledgements
A Python package with utilities for deep-sky observations. This version of pydeepskylog provides the following functionality:
- Calculating of contrast reserve and optimal detection magnification for deep-sky objects.
- Conversion of magnitudes to SQM value and bortle scale and vice versa.
- Fetching instruments, eyepieces, lenses, and filters from a DeepskyLog user account.
Install via pip:
pip install pydeepskylogDevelopment dependencies can be installed with:
pip install -e .[dev]Import the main modules:
import pydeepskylog.magnitude as mag
import pydeepskylog.contrast_reserve as crConvert NELM to SQM:
sqm = mag.nelm_to_sqm(6.2)
print(f"SQM: {sqm:.2f}")Convert SQM to Bortle scale:
bortle = mag.sqm_to_bortle(21.0)
print(f"Bortle class: {bortle}")Calculate the contrast reserve for an object:
reserve = cr.contrast_reserve(
sqm=21.0,
telescope_diameter=200, # mm
magnification=100,
surf_brightness=None,
magnitude=10.5,
object_diameter1=120, # arcsec
object_diameter2=60 # arcsec
)
print(f"Contrast reserve: {reserve:.2f}")Find the best magnification for detection:
magnifications = [50, 75, 100, 150, 200]
optimal = cr.optimal_detection_magnification(
sqm=21.0,
telescope_diameter=200,
surf_brightness=None,
magnitude=10.5,
object_diameter1=120,
object_diameter2=60,
magnifications=magnifications
)
print(f"Optimal magnification: {optimal}")Fetch user instruments:
from pydeepskylog.deepskylog_interface import dsl_instruments
instruments = dsl_instruments("your_username")
for inst_id, inst in instruments.items():
print(inst["name"], inst["diameter"])The API endpoints are documented in the API Endpoints section.
Validate a positive number:
from pydeepskylog.validation import validate_positive
validate_positive(42, "Telescope diameter")Set up logging for debugging:
from pydeepskylog.logging_config import configure_logging
import logging
configure_logging(logging.DEBUG)Documentation for the API is available at Read the Docs.
The contrast reserve is a measure of the difference in brightness between the object and the sky background. It is calculated as the difference between the object's surface brightness and the sky background brightness. The contrast reserve is a useful metric for determining the visibility of deep sky objects through a telescope.
The higher the contrast reserve, the easier it is to see the object. The following table can be used to interpret the contrast reserve:
| Contrast Reserve | Visibility | Typical color |
|---|---|---|
| < -0.2 | Not visible | dark grey |
| -0.2 < CR < 0.1 | Questionable | light grey |
| 0.1 < CR < 0.35 | Difficult | dark red |
| 0.35 < CR < 0.5 | Quite difficult to see | light red |
| 0.5 < CR < 1.0 | Easy to see | dark green |
| 1.0 < CR | Very easy to see | light green |
The contrast reserved is calculated for the object as a whole. Smaller details in the object might be visible even if the contrast reserve of the object as a whole is below -0.2. This is certainly the case for galaxies, where the core might be much brighter than the outer regions.
It is important to note that the contrast reserve is a theoretical value and that the actual visibility of an object will depend on a number of other factors, including the observer's experience, the transparency of the sky, and the seeing conditions. The contrast reserve is just a guideline.
The calculation of the contrast reserve depends heavily on the quality of the object database. A small error in the object's magnitude or size can lead to a large error in the contrast reserve.
Only if the observer tries to observe the object, he/she will know if the object is visible or not.
The optimal detection magnification is the magnification at which the object is most easily visible. Take into account that the optimal detection magnification is not the same as the best magnification for observing details in an object, but for the object as a whole.
Conversion methods are provided to convert magnitudes to SQM value and bortle scale and vice versa.
Different formulae are available to convert magnitudes to SQM value. The formula used here converts a sqm value of 22.0 to a naked eye limiting magnitude of 6.6. The faintest star offset can be given to the formula. If taking a value of -1.4 for the faintest star offset, the formula converts a sqm value of 22.0 to a naked eye limiting magnitude of 8.0.
| Measurement | Description | Conversion Functions |
|---|---|---|
| NELM | Naked Eye Limiting Magnitude, the faintest star visible to the naked eye under ideal conditions. | nelm_to_sqm(), nelm_to_bortle() |
| SQM | Sky Quality Meter, a measure of sky brightness in magnitudes per square arcsecond. | sqm_to_nelm(), sqm_to_bortle() |
| Bortle Scale | A qualitative scale that classifies the night sky based on light pollution and visibility. | bortle_to_nelm(), bortle_to_sqm() |
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. See CONTRIBUTING.md for details on how to contribute.
See CHANGELOG.md for a detailed list of changes and updates to the package.
This package is inspired by the DeepskyLog website and the code is based on the formulas used in DeepskyLog. We would like to thank the DeepskyLog developers team.