{"id":16323928,"url":"https://github.com/bonnie/my_heavens","last_synced_at":"2025-03-22T21:32:48.013Z","repository":{"id":110358868,"uuid":"80571864","full_name":"bonnie/my_heavens","owner":"bonnie","description":"Web app to visualize the stars and planets at a particular date and time","archived":false,"fork":false,"pushed_at":"2020-09-15T23:31:50.000Z","size":6293,"stargazers_count":5,"open_issues_count":10,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T15:16:15.404Z","etag":null,"topics":["astronomy","bootstrap","css","d3-geo","flask","html","javascript","jquery","postgresql","python","python-2","sqlalchemy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bonnie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-31T23:11:19.000Z","updated_at":"2020-09-15T23:31:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"20b036bb-90cf-4d2e-8f78-af276890453e","html_url":"https://github.com/bonnie/my_heavens","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnie%2Fmy_heavens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnie%2Fmy_heavens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnie%2Fmy_heavens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnie%2Fmy_heavens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bonnie","download_url":"https://codeload.github.com/bonnie/my_heavens/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245023395,"owners_count":20548721,"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","bootstrap","css","d3-geo","flask","html","javascript","jquery","postgresql","python","python-2","sqlalchemy"],"created_at":"2024-10-10T22:56:06.836Z","updated_at":"2025-03-22T21:32:47.990Z","avatar_url":"https://github.com/bonnie.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# My Heavens \n### An open-source view of the stars and planets\n[![Build Status](https://travis-ci.org/flyrightsister/my_heavens.svg?branch=master)](https://travis-ci.org/flyrightsister/my_heavens)\n\n## Contents\n\n1. [Deployed Site](#deployed-site)\n2. [License](#license)\n3. [Overview](#overview)\n4. [Data Sources](#data-sources)\n5. [Tech Stack](#tech-stack)\n6. [d3](#d3)\n7. [Testing](#testing)\n8. [Sticking Points](#sticking-points)\n9. [Future Development](#future-development)\n10. [About the Author](#about-the-author)\n\n## License\n\nMy Heavens is licensed under the [GNU Affero General Public\nLicense](http://www.gnu.org/licenses/).\n\n## Overview\n\nMy Heavens is a web app \ninspired by Zoe Gotch-Strain's stellar (sorry, couldn't resist) [Hackbright\nStudent Project](https://github.com/ZoeShirah/Hackbright_Star_Project). The site\nallows the user to enter a time and location, and it will show the configuration\nof stars and planets (and sun and moon) as viewed from that time and place.\nMouseovers reveal constellations, and clicking on a sky object brings up more\ninformation about the object. Clicking an astronomical term shows a brief\ndefinition, as well as a link to more complete information on Wikipedia.\nFinally, since astronomers value night vision, there is a \"night mode\" which\nlimits the color palette to a night-vision friendly red.\n\nOne thing the app does not do: take into account proper motion of the stars\n(that is, the movement of the stars relative to one another). The configuration\nof the stars will not change regardless of the date entered.\n\n## Data Sources\n\n#### Star cooridnates, magnitude, distance, spectral type, names, constellations\n\u003chttp://astronexus.com/files/downloads/hygfull.csv.gz\u003e\n\n#### Mapping constellation abbreviations to names\n\u003chttps://ircatalog.gsfc.nasa.gov/constel_names.html\u003e\n\n#### Coordinates of constellation boundaries\n\u003chttp://pbarbier.com/constellations/boundaries.html#bnd18\u003e\n\n#### Constellation lines\n\u003chttp://observe.phy.sfasu.edu/SFAStarCharts/ExcelCharts/ConstellationLinesAll2002.xls\u003e\n\n#### Mapping spectral type to hex color\n\u003chttp://www.vendian.org/mncharity/dir3/starcolor/UnstableURLs/starcolors.txt\u003e\n\n\n## Tech Stack\n\n- **PostgreSQL** \n\n    for stars, constellations, constellation boundaries, constellation lines\n\n- **Python** \n\n    for processing database data and some calculations (such as apparent moon\n    rotation in the sky field as seen on the web site)\n\n- **Flask** \n\n    for serving the initial HTML and returing JSON for the [d3](#d3)\n\n- **JavaScript/JQuery**\n\n    for general page manipulation, and switching between pages (this is a\n    one-page app, with different page views managed by JavaScript and CSS)\n\n- **[d3](#d3)**\n\n    for projecting stars and constellations onto three-dimensional sky sphere.\n    [See below](#d3) for more details\n\n## d3\n\nThe presentation of the star field relies heavily on\n[d3-geo](https://github.com/d3/d3/blob/master/API.md#geographies-d3-geo). The\nstars, planets, constellations, and all other sky objects are projected onto a\nthree-dimensional d3-geo sphere representing the sky. All star coordinates\nneeded to be reversed, since d3 presents the outside of the sphere, but the\nviewers need to have the illusion that they are looking at the inside of the\nsphere. \n\nThis turns out to be a very efficient way to present the stars at an arbitrary\nviewing location and time, since there is no need to calculate positions of\nstars as the viewer would see them. An analogy to help understand this\nefficiency: if you wanted to display the earth as viewed from a certain location\nin space (say, the moon) at a certain time (say, right now), you could either:\n\na. Draw the earth as a circle, determining exactly what the earth would look\n   like for that viewer and drawing the visible continents precisely positioned, or\n\nb. draw *all* the continents on a sphere, and then rotate the\n   sphere to display the half that our particular user would see (of course, on\n   a two-dimensional screen, a sphere is flattened to a circle -- so what the user\n   actually sees looks identical to choice (a)).\n\nThis app uses option (b) to approach showing the stars. This means the stars and\ntheir locations need to load only once, when the app first loads. Any\nrepositioning of the user in time or space simply requires rotating the sphere\nof the sky --- whose star data is already plotted --- to represent that view.\n\nSince the planets, sun and moon move against the background of the stars, these\nneed to be re-plotted with each newly entered time. However, there are very\nfew of these compared to the thousands of visible stars in the sky, so this\ntakes a negligible amount of time.\n\n## Testing\n\nAs of the time of writing this readme (May 2, 2017), 100% of the Python code is\ncovered by unit tests, and a [Travis](https://travis-ci.org) integration runs\nthe tests with every GitHub push. 0% of the JavaScript is tested (see [Future\nDevelopment](#future-development)).\n\nThe app was developed using Chrome 57.0.2987.133 (64-bit) on Mac OS X 10.11.5.\nThere has been no testing with other browsers or platforms.\n\n## Sticking Points\n\nSome interesting technical issues arose in the making of this app. \n\n### Constellation boundaries\n\nThe constellation boundaries were d3 polygons projected onto a sphere. I wanted\nto use these boundary polygons to trigger the constellation visibility on\nmouseover --- but I was stymied when some polygons seemed to take up the whole\nsky, covering any constellation polygons that had come before them. \n\nThis was a tough one -- it took a while even to figure out what to google to\nremedy this. It turns out that the polygons for these constellation \"space hogs\"\nwere inverted, so that the \"interior\" of the polygon was everything *but* the\nconstellation, instead of the constellation itself. The inversion occurred when\nthe constellation boundary coordinates were counter-clockwise instead of\nclockwise.\n\nHelpful web sites for this: \n    \n\u003chttps://github.com/d3/d3/issues/2051\u003e\n\n\u003chttps://bl.ocks.org/mbostock/a7bdfeb041e850799a8d3dce4d8c50c8\u003e\n\n### How to rotate the sky sphere\n\nI needed to figure out how to rotate the sphere of the sky to represent the view\nthat the user would see for the desired place and time. This was a lot more\ndifficult that I thought it would be, and required way more wikipedia reading\nand dredging up of college astronomy than I expected.\n\nBasically, I wanted to provide a declination (which happens to be the latitude)\nand an altitude (90 degrees), and get the right ascension (which will determine\nhow much the sky sphere needs to rotate). \n\nI eventually worked out that I could use the hour angle from the [sidereal\npython library](http://infohost.nmt.edu/tcc/help/lang/python/examples/sidereal/)\nto get the desired rotation.\n\n### How to draw the moon phase\n\nI wanted to draw the moon in its current phase, and the easiest(!) way to do\nthis seemed to be:\n\n- make a little d3 sphere for the moon\n\n- light up half of it\n\n- rotate the correct part of the lit half into view\n\nThankfully, the [pyEphem python library](http://rhodesmill.org/pyephem/)\nprovides the selenegraphic colongitude of the moon (which is the angle of the\nterminus of the lit hemisphere --- more wikipedia research!). Also, you can't\nproject a d3 sphere (i.e. the moon) onto another d3 sphere (the sky), so the\nmoon would show up regardless of whether it was on the \"right\" side of the sky\nsphere. I needed to make a proxy point for the moon's location in the sky,\ndetermine whether that point was visible, and only show the moon in that case.\n\n### How to rotate the moon\n\nThis was by far the most vexing technical problem of this app, thanks to a\ncombination of mathematical obscurity and programmer error. The most helpful\nlink for this was a formula from this paper:\n\n\u003chttps://planetarium.madison.k12.wi.us/mooncal/crescent-tilt/Crescent.html\u003e\n\nEven with that formula, it took me many, many hours to determine how to rotate\nthe moon sphere so that the axis of the phase was properly perpendicular to the\necliptic -- or in more layman's terms, so that the points of the crescent\npointed in the right direction. The \"show ecliptic\" feature was mostly so I\ncould check to see whether the moon was correctly rotated.\n\n### Serpens\n\nSerpens is the \"problem child\" of the constellations --- it has two distinct\nboundary polygons (imagine if the state of California was both California and\nWashington). I ultimately decided it wasn't worth structuring the database\naround this oddity (Serpens is the only constellation with two boundary\npolygons, and the constellations are fixed and unchanging), so Serpens has\nits own dedicated code for processing its special configuration.\n\n### Deployment and tzwhere\n\nIt turns out the utility I was using for getting a time zone from latitude and\nlongitude -- [tzwhere](https://pypi.python.org/pypi/tzwhere) -- is quite memory\nintensive. So memory intensive, in fact that the lowest tier of AWS LightSail\nrefuses to run it. I went down a false path of trying the less-memory intensive\n[geopy](https://pypi.python.org/pypi/geopy/1.11.0) for timezone lookup -- but\nsadly, it was also less reliable. My Travis tests would sporadically fail when\nthis service failed.\n\nUltimately, I went with using tzwhere in conjunction with numpy to reduce memory\nusage. This slows down the travis tests considerably, though, since numpy takes\na long time to pip install.\n\n## Future Development\n\nOpen issues are [tracked via\nGitHub](https://github.com/flyrightsister/my_heavens/issues).\n\nPlease send all bug reports and feature requests to admin@myheavens.space. This\nis a hobby project, so there are no guarantees of follow-through!\n\n## About the Author\n\nBonnie Schulkin is a teacher, coder, and astronomer (in that order). This app is\na fun combination of all three.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnie%2Fmy_heavens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonnie%2Fmy_heavens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnie%2Fmy_heavens/lists"}