{"id":15038428,"url":"https://github.com/djben/starrynight","last_synced_at":"2025-10-29T10:03:07.350Z","repository":{"id":64059983,"uuid":"105240947","full_name":"DJBen/StarryNight","owner":"DJBen","description":"Star and constellation query in Swift 4. 15000+ stars within 7th magnitude (can be extended). Star Catalogs including HR, HD, HIP, Gould and Bayer-Flamsteed designations.","archived":false,"fork":false,"pushed_at":"2017-12-30T03:12:40.000Z","size":6181,"stargazers_count":14,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T03:04:30.896Z","etag":null,"topics":["astronomy","carthage","constellation","swift-4"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DJBen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-29T07:04:25.000Z","updated_at":"2024-05-11T00:54:27.000Z","dependencies_parsed_at":"2023-01-14T20:30:38.178Z","dependency_job_id":null,"html_url":"https://github.com/DJBen/StarryNight","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJBen%2FStarryNight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJBen%2FStarryNight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJBen%2FStarryNight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DJBen%2FStarryNight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DJBen","download_url":"https://codeload.github.com/DJBen/StarryNight/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248138530,"owners_count":21053867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["astronomy","carthage","constellation","swift-4"],"created_at":"2024-09-24T20:38:29.795Z","updated_at":"2025-10-29T10:03:07.337Z","avatar_url":"https://github.com/DJBen.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Title image](S-Green.png)\n\n# StarryNight\nHigh performance star catalog and constellation data layer backed by SQLite and H3 index to power planetarium and star charts.\n\n## Features\n\n- **Multi-level Detail Star Catalog**: Stars are grouped into 4 levels for different zoom levels: brightest 300 (up to mag 3.5), H3 level 0 (up to mag 6.1), H3 level 1 (up to mag 8.0), H3 level 2 (up to mag 21). At any time only up to ~300 of stars will be rendered within the viewport.\n- **H3 Spatial Indexing**: Efficient spatial queries using Uber's H3 hexagonal hierarchical spatial index\n- **Comprehensive Catalogs**: Includes Hipparcos, Henry Draper, Harvard Revised catalogs\n- **Constellation Data**: Full IAU constellation boundaries and traditional connection lines\n- **Star Names**: Proper names, Bayer-Flamsteed designations, and catalog numbers\n- **Spectral Classification**: Stellar spectral types for accurate color rendering\n\n## Quick Start\n\n### Swift Package Manager Integration\n\nAdd StarryNight to your project by adding the following dependency to your `Package.swift`:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/DJBen/StarryNight.git\", from: \"1.0.0\"),\n]\n```\n\nOr add it through Xcode:\n1. File → Add Package Dependencies\n2. Enter the repository URL\n3. Add to your target\n\n### Basic Usage\n\n```swift\nimport StarryNight\n\n// Initialize the star manager\nlet starManager = StarManager()\n\n// Get the brightest stars for display\nlet brightStars = starManager.brightestStars()\n\n// Get stars up to magnitude 6.0 (naked eye limit)\nlet visibleStars = starManager.stars(maximumMagnitude: 6.0)\n\n// Search for a specific star\nlet searchResults = starManager.searchStars(matching: \"Sirius\")\n\n// Get detailed star information\nif let starId = searchResults.first?.id {\n    let starInfo = starManager.starInfo(forId: starId)\n    print(\"Star: \\(starInfo?.properName ?? \"Unknown\")\")\n}\n```\n\n### Common Query Examples\n\n#### Working with Star Data\n\n```swift\n// Get stars for a specific view (viewport-based query)\nlet viewport = [\n    (latitude: 40.0, longitude: -74.0),  // New York area\n    (latitude: 41.0, longitude: -74.0),\n    (latitude: 41.0, longitude: -73.0),\n    (latitude: 40.0, longitude: -73.0)\n]\nlet starsInView = starManager.stars(inViewport: viewport, maximumMagnitude: 5.0)\n\n// Find the closest star to a coordinate\nlet coordinate = Vector(x: 0.5, y: 0.5, z: 0.7)\nlet nearestStar = starManager.closestStar(\n    to: coordinate, \n    maximumMagnitude: 6.0, \n    maximumAngularDistance: 0.1\n)\n\n// Get stars by H3 spatial indexing\nlet h3Stars = starManager.stars(forH3Level: 2, maximumMagnitude: 4.0)\n```\n\n#### Working with Constellations\n\n```swift\n// Get all constellations\nlet allConstellations = starManager.allConstellations()\n\n// Find a specific constellation\nlet orion = starManager.constellation(iau: \"ORI\")\nlet ursa = starManager.constellation(named: \"Ursa Major\")\n\n// Get constellation connection lines for drawing\nif let constellation = orion {\n    let lines = starManager.constellationLines(for: constellation)\n    // Use lines to draw constellation patterns\n}\n\n// Find neighboring constellations\nif let constellation = orion {\n    let neighbors = starManager.neighbors(for: constellation)\n}\n```\n\n#### Star Naming and Identifiers\n\n```swift\n// Stars can have multiple naming systems\nlet star = starManager.star(withId: 12345)\nif let starInfo = star?.info {\n    print(\"Hipparcos: \\(starInfo.hipparcos ?? 0)\")\n    print(\"Henry Draper: \\(starInfo.henryDraper ?? 0)\")\n    print(\"Harvard Revised: \\(starInfo.harvardRevised ?? 0)\")\n    print(\"Proper name: \\(starInfo.properName ?? \"None\")\")\n    \n    // Bayer-Flamsteed designations (e.g., \"α Orionis\")\n    if let bf = starInfo.bayerFlamsteed {\n        print(\"Designation: \\(bf.description)\")\n    }\n}\n```\n\n#### Performance Considerations\n\n```swift\n// For real-time applications, use appropriate magnitude limits\n// Brightest 300 stars - always fast\nlet brightStars = starManager.brightestStars()\n\n// For zoomed out views, use higher magnitude limits\nlet allVisibleStars = starManager.stars(maximumMagnitude: 6.0)\n\n// For detailed views, you can go fainter but expect more data\nlet faintStars = starManager.stars(maximumMagnitude: 9.0)\n\n// Use H3 indexing for spatial queries when possible\nlet localStars = starManager.stars(\n    inH3Cell: \"8428309ffffffff\", \n    level: 2, \n    maximumMagnitude: 7.0\n)\n```\n\n### Thread Safety\n\nAll StarManager operations are thread-safe and marked as `Sendable`. The underlying SQLite database supports concurrent reads.\n\n## Sources and transformations\nThe stars DB comes from [HYG database](https://www.astronexus.com/projects/hyg), available as csv.\n\n## License\n\nStarryNight is available under the MIT license. See the LICENSE file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjben%2Fstarrynight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjben%2Fstarrynight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjben%2Fstarrynight/lists"}