# PyStarTrails
This package can be used by astrophotographers and photographers to create stunning images of the night sky by generating star trails from a sequence of images, and also create beautiful time-lapse videos.
The previous image-processing software I used was Adobe Photoshop, a powerful image-processing program that can be used for the generation of star trails. However, I experienced slow computer performance after uploading a star trail image sequence (more than 500 images) because my RAM became overloaded. I was forced to divide the 500 images into small batches and this process took a considerable amount of time.
Due to this, I have decided to develop a lightweight and fast python package that does not require the installation of any external programs. I hope that this package will be useful for all astrophotographers and photographers worldwide :)
Developed by [Yassir LAIRGI](https://lairgiyassir.github.io/) ©2022.
# Installation
The PyStarTrails package can be installed through pip:
```bash
pip install pystartrails
```
# Usage
## Star Trails Generation
The package assumes that you already have a sequence of night sky images from which you would like to create a star-trail image. In order create your first star-trail image, specify :
``` python
from pystartrails import TrailsAndTimeLapseGenerator
trails_generator = TrailsAndTimeLapseGenerator(
sequence_repository=sequence_repository,
generated_img_name=generated_img_name,
generated_img_extension=generated_img_extension,
generated_img_repository=generated_img_repository,
fps=10 # For time-lapse videos
)
star_trail_img = trails_generator.generate_trails()
```
### Parameters:
- **sequence_repository** (str): The image sequence repository (please be sure that your images have the same shape).
- **generated_img_name** (str): The name of your generated image (star trailed image)
- **generated_img_extension** (str): The extension of your generated image (either "JPG", "JPEG" or "PNG")
- **generated_img_repository** (str, optional): Here you specify where you want to save your generated trailed image. By default, the generated image is stored in the sequence repository
- **fps** (int, default=10): Frames per second for time-lapse videos
- **output_extension** (str, default='mp4'): The extension of the output time-lapse video
### The `generate_trails()` method:
The `generate_trails()` method returns array in the same format as the input format and saves the generated image in the specified generated_img_repository.
**Parameters:**
- **n_images** (int, optional): Number of images to use from the sequence. If not specified, all images are used. This parameter controls how many images from your sequence will be processed to create the star trails. For example, if you have 100 images and set `n_images=20`, the method will process every 5th image (100/20=5) to create the trails, making the process faster but potentially less detailed.
```python
# Use all images in the sequence
star_trail_img = trails_generator.generate_trails()
# Use only 20 images from the sequence (evenly distributed)
star_trail_img = trails_generator.generate_trails(n_images=20)
```
## Time-lapse Video Creation
The package also supports creating time-lapse videos from your image sequence:
### Regular Time-lapse (without blending):
```python
from pystartrails import TrailsAndTimeLapseGenerator
trails_generator = TrailsAndTimeLapseGenerator(
sequence_repository="../data/raw/",
generated_img_name="timelapse_img",
generated_img_extension="JPG",
fps=30
)
# Create a regular time-lapse video
trails_generator.create_timelapse(
blended_timelapse=False,
output_filename="my_timelapse"
)
```
**Output - Regular Time-lapse:**
[📹 View Regular Time-lapse Video](docs/regular_timelapse.mp4)
### Blended Time-lapse (with star trails accumulation):
```python
# Create a blended time-lapse video where star trails accumulate over time
trails_generator.create_timelapse(
blended_timelapse=True,
output_filename="my_blended_timelapse"
)
```
**Output - Blended Time-lapse:**
[📹 View Blended Time-lapse Video](docs/blended_timelapse.mp4)
**The difference:**
- **blended_timelapse=False**: Creates a regular time-lapse video showing each frame as-is
- **blended_timelapse=True**: Creates a blended time-lapse where star trails accumulate progressively, showing the star trails building up over time
### Video Examples:
**Regular Time-lapse Example:**
[📹 View Regular Time-lapse Video](docs/regular_timelapse.mp4)
**Blended Time-lapse Example (with accumulating star trails):**
[📹 View Blended Time-lapse Video](docs/blended_timelapse.mp4)
# Example
This example demonstrates both star trails generation and time-lapse creation:
1. Prepare the folder of your night sky image sequence. This repository is actually the sequence_repository attribute of TrailsAndTimeLapseGenerator class.
2. Choose the generated image extension and where you want to save it (otherwise, it will be stored by default in the sequence repository).
3. Generate your star trail image and create time-lapse videos:
``` python
from pystartrails import TrailsAndTimeLapseGenerator
# Initialize the TrailsAndTimeLapseGenerator class
trails_generator = TrailsAndTimeLapseGenerator(
sequence_repository="../data/raw/",
generated_img_extension="JPG",
generated_img_name="trailed_img",
fps=24
)
# Generate trails using all images
star_trail_img = trails_generator.generate_trails()
# Generate trails using only 50 images (faster processing)
star_trail_img_fast = trails_generator.generate_trails(n_images=50)
# Create a regular time-lapse video
trails_generator.create_timelapse(
blended_timelapse=False,
output_filename="regular_timelapse"
)
# Create a blended time-lapse video with accumulating star trails
trails_generator.create_timelapse(
blended_timelapse=True,
output_filename="blended_timelapse"
)
"""
OUTPUT
100%|██████████| 10/10 [00:04<00:00, 2.17it/s]
100%|██████████| 10/10 [00:02<00:00, 4.50it/s]
100%|██████████| 10/10 [00:15<00:00, 1.50it/s]
Timelapse video saved as regular_timelapse.mp4
100%|██████████| 10/10 [00:18<00:00, 1.35it/s]
Timelapse video saved as blended_timelapse.mp4
"""
```
You can also display the generated image using matplotlib:
``` python
import matplotlib.pyplot as plt
plt.imshow(star_trail_img)
plt.show()
```
### Example Time-lapse Video:
Here's an example of a time-lapse video created using PyStarTrails:
[📹 View Example Time-lapse Video](docs/example_of_timelapse.mp4)
# Dependencies
The PyStarTrails package needs the following packages:
* [matplotlib](https://matplotlib.org/stable/index.html)
* [NumPy](https://numpy.org/)
* [OpenCV](https://opencv.org/)
* [tqdm](https://tqdm.github.io/)
# See Also
All my star trail images were generated using this package. You could check my Instagram account [Yassir LAIRGI](https://www.instagram.com/lairgi_yassir).
# Contribution
Feel free to contact me via the Issues tab on GitHub if you would like to contribute or provide feedback.
# License
Please note that the PyStarTrails package is distributed under the MIT License (MIT).
Raw data
{
"_id": null,
"home_page": "https://github.com/yassirlairgi/PyStarTrails",
"name": "pystartrails",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "python, star trails, astrophotography, photography, blending modes, time-lapse, image processing, astronomy",
"author": "Yassir LAIRGI",
"author_email": "yassirlairgi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7a/f6/fdc0fe268a8c2e417f4ac8d09511e554687524ad147aca5dff3f3041ccec/pystartrails-0.1.0.tar.gz",
"platform": null,
"description": "# PyStarTrails\n\n![alt text](docs/logo.png \"PyStarTrails Logo\")\n\nThis package can be used by astrophotographers and photographers to create stunning images of the night sky by generating star trails from a sequence of images, and also create beautiful time-lapse videos.\n\nThe previous image-processing software I used was Adobe Photoshop, a powerful image-processing program that can be used for the generation of star trails. However, I experienced slow computer performance after uploading a star trail image sequence (more than 500 images) because my RAM became overloaded. I was forced to divide the 500 images into small batches and this process took a considerable amount of time. \n\nDue to this, I have decided to develop a lightweight and fast python package that does not require the installation of any external programs. I hope that this package will be useful for all astrophotographers and photographers worldwide :) \n\nDeveloped by [Yassir LAIRGI](https://lairgiyassir.github.io/) \u00a92022. \n\n# Installation\nThe PyStarTrails package can be installed through pip:\n\n```bash\npip install pystartrails\n```\n\n# Usage\n\n## Star Trails Generation\n\nThe package assumes that you already have a sequence of night sky images from which you would like to create a star-trail image. In order create your first star-trail image, specify : \n\n``` python\nfrom pystartrails import TrailsAndTimeLapseGenerator\n\ntrails_generator = TrailsAndTimeLapseGenerator(\n sequence_repository=sequence_repository, \n generated_img_name=generated_img_name,\n generated_img_extension=generated_img_extension, \n generated_img_repository=generated_img_repository,\n fps=10 # For time-lapse videos\n)\nstar_trail_img = trails_generator.generate_trails()\n```\n\n### Parameters:\n\n- **sequence_repository** (str): The image sequence repository (please be sure that your images have the same shape).\n- **generated_img_name** (str): The name of your generated image (star trailed image) \n- **generated_img_extension** (str): The extension of your generated image (either \"JPG\", \"JPEG\" or \"PNG\") \n- **generated_img_repository** (str, optional): Here you specify where you want to save your generated trailed image. By default, the generated image is stored in the sequence repository\n- **fps** (int, default=10): Frames per second for time-lapse videos\n- **output_extension** (str, default='mp4'): The extension of the output time-lapse video\n\n### The `generate_trails()` method:\n\nThe `generate_trails()` method returns array in the same format as the input format and saves the generated image in the specified generated_img_repository.\n\n**Parameters:**\n- **n_images** (int, optional): Number of images to use from the sequence. If not specified, all images are used. This parameter controls how many images from your sequence will be processed to create the star trails. For example, if you have 100 images and set `n_images=20`, the method will process every 5th image (100/20=5) to create the trails, making the process faster but potentially less detailed.\n\n```python\n# Use all images in the sequence\nstar_trail_img = trails_generator.generate_trails()\n\n# Use only 20 images from the sequence (evenly distributed)\nstar_trail_img = trails_generator.generate_trails(n_images=20)\n```\n\n## Time-lapse Video Creation\n\nThe package also supports creating time-lapse videos from your image sequence:\n\n### Regular Time-lapse (without blending):\n\n```python\nfrom pystartrails import TrailsAndTimeLapseGenerator\n\ntrails_generator = TrailsAndTimeLapseGenerator(\n sequence_repository=\"../data/raw/\", \n generated_img_name=\"timelapse_img\",\n generated_img_extension=\"JPG\", \n fps=30\n)\n\n# Create a regular time-lapse video\ntrails_generator.create_timelapse(\n blended_timelapse=False, \n output_filename=\"my_timelapse\"\n)\n```\n\n**Output - Regular Time-lapse:**\n\n[\ud83d\udcf9 View Regular Time-lapse Video](docs/regular_timelapse.mp4)\n\n### Blended Time-lapse (with star trails accumulation):\n\n```python\n# Create a blended time-lapse video where star trails accumulate over time\ntrails_generator.create_timelapse(\n blended_timelapse=True, \n output_filename=\"my_blended_timelapse\"\n)\n```\n\n**Output - Blended Time-lapse:**\n\n[\ud83d\udcf9 View Blended Time-lapse Video](docs/blended_timelapse.mp4)\n\n**The difference:**\n- **blended_timelapse=False**: Creates a regular time-lapse video showing each frame as-is\n- **blended_timelapse=True**: Creates a blended time-lapse where star trails accumulate progressively, showing the star trails building up over time\n\n### Video Examples:\n\n**Regular Time-lapse Example:**\n\n[\ud83d\udcf9 View Regular Time-lapse Video](docs/regular_timelapse.mp4)\n\n**Blended Time-lapse Example (with accumulating star trails):**\n\n[\ud83d\udcf9 View Blended Time-lapse Video](docs/blended_timelapse.mp4)\n\n# Example\n\nThis example demonstrates both star trails generation and time-lapse creation:\n\n1. Prepare the folder of your night sky image sequence. This repository is actually the sequence_repository attribute of TrailsAndTimeLapseGenerator class. \n\n![alt text](docs/img_sequence.png \"Image sequence repository\")\n\n2. Choose the generated image extension and where you want to save it (otherwise, it will be stored by default in the sequence repository).\n\n3. Generate your star trail image and create time-lapse videos:\n\n``` python\nfrom pystartrails import TrailsAndTimeLapseGenerator\n\n# Initialize the TrailsAndTimeLapseGenerator class\ntrails_generator = TrailsAndTimeLapseGenerator(\n sequence_repository=\"../data/raw/\", \n generated_img_extension=\"JPG\", \n generated_img_name=\"trailed_img\",\n fps=24\n)\n\n# Generate trails using all images\nstar_trail_img = trails_generator.generate_trails()\n\n# Generate trails using only 50 images (faster processing)\nstar_trail_img_fast = trails_generator.generate_trails(n_images=50)\n\n# Create a regular time-lapse video\ntrails_generator.create_timelapse(\n blended_timelapse=False, \n output_filename=\"regular_timelapse\"\n)\n\n# Create a blended time-lapse video with accumulating star trails\ntrails_generator.create_timelapse(\n blended_timelapse=True, \n output_filename=\"blended_timelapse\"\n)\n\n\"\"\"\nOUTPUT\n\n100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 10/10 [00:04<00:00, 2.17it/s]\n100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 10/10 [00:02<00:00, 4.50it/s]\n100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 10/10 [00:15<00:00, 1.50it/s]\nTimelapse video saved as regular_timelapse.mp4\n100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 10/10 [00:18<00:00, 1.35it/s]\nTimelapse video saved as blended_timelapse.mp4\n\"\"\"\n```\n\nYou can also display the generated image using matplotlib:\n\n``` python\nimport matplotlib.pyplot as plt \n\nplt.imshow(star_trail_img)\nplt.show()\n```\n\n![alt text](docs/generated_img.jpg \"The generated star trails image\")\n\n### Example Time-lapse Video:\n\nHere's an example of a time-lapse video created using PyStarTrails:\n\n[\ud83d\udcf9 View Example Time-lapse Video](docs/example_of_timelapse.mp4)\n\n# Dependencies\nThe PyStarTrails package needs the following packages:\n\n* [matplotlib](https://matplotlib.org/stable/index.html)\n* [NumPy](https://numpy.org/)\n* [OpenCV](https://opencv.org/)\n* [tqdm](https://tqdm.github.io/)\n\n# See Also\nAll my star trail images were generated using this package. You could check my Instagram account [Yassir LAIRGI](https://www.instagram.com/lairgi_yassir).\n\n# Contribution\nFeel free to contact me via the Issues tab on GitHub if you would like to contribute or provide feedback.\n\n# License\nPlease note that the PyStarTrails package is distributed under the MIT License (MIT).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate stunning star trail images and time-lapse videos from night sky image sequences",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/yassirlairgi/PyStarTrails",
"Homepage": "https://github.com/yassirlairgi/PyStarTrails",
"Source": "https://github.com/yassirlairgi/PyStarTrails",
"Tracker": "https://github.com/yassirlairgi/PyStarTrails/issues"
},
"split_keywords": [
"python",
" star trails",
" astrophotography",
" photography",
" blending modes",
" time-lapse",
" image processing",
" astronomy"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c427a8a7cacbb40e3b7cf80bd50ae01672e967a7cb3cc397ea987f0a8d28858b",
"md5": "642abb75433fddc23f133ac9b7900974",
"sha256": "279a2a29a3042c8fc75e6e0ec397e545617ac83f8589840387d4041081d439f3"
},
"downloads": -1,
"filename": "pystartrails-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "642abb75433fddc23f133ac9b7900974",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9429,
"upload_time": "2025-07-13T23:22:01",
"upload_time_iso_8601": "2025-07-13T23:22:01.056894Z",
"url": "https://files.pythonhosted.org/packages/c4/27/a8a7cacbb40e3b7cf80bd50ae01672e967a7cb3cc397ea987f0a8d28858b/pystartrails-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7af6fdc0fe268a8c2e417f4ac8d09511e554687524ad147aca5dff3f3041ccec",
"md5": "0c4e97c0912abf30e0c185562f5366a9",
"sha256": "c2d066bc75cc4186e88a79829ef2a68d4cec3399d2078f63728d6dc5e46bfd28"
},
"downloads": -1,
"filename": "pystartrails-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0c4e97c0912abf30e0c185562f5366a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11315,
"upload_time": "2025-07-13T23:22:02",
"upload_time_iso_8601": "2025-07-13T23:22:02.180170Z",
"url": "https://files.pythonhosted.org/packages/7a/f6/fdc0fe268a8c2e417f4ac8d09511e554687524ad147aca5dff3f3041ccec/pystartrails-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 23:22:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yassirlairgi",
"github_project": "PyStarTrails",
"github_not_found": true,
"lcname": "pystartrails"
}
JSON
