Add capability to plot own data on a chart

[sizzzzlerz]

Is your feature request related to a problem? Please describe.
I want to be able to display my own data on a chart. As an example, I want to plot the location of the planets against the background at specific points in time over the course of a month or so. Using Skyfield, I can compute planet locations as a function of the date. It will return the RA/DEC at each time point. I then would use that data to plot symbols on the chart and the appropriate location. For the outer planets, only a single point would be needed but the inner planets would move over the course of a month so I could show the beginning and ending. This is similar to the charts found in Astronomy and Sky & Telescope magazines.

Describe the solution you'd like
An interface to the plot object where I would pass a list of RAs and DECs and have it return a list of x,y locations that could then be passed directly to the matplotlib plot function without a further transformation. My code would be responsible for all the styling (color, symbol, line widths, etc.)

Describe alternatives you've considered
I tried modeling a solution on the ecliptic function but the plot scaling is wrong. In addition, several functions are not part of the public interface.

Additional context
Add any other context or screenshots about the feature request here.

[steveberardi]

For the planets, one thing you can do (that exists today in Starplot) is iterate through the days you want to show the planet positions, and then get Planet instances for each day and plot them as markers. Here's some pseudocode:

p = <your plot instance>

for dt in dates:
  for planet in Planet.all(dt):
     p.marker(
       ra=planet.ra,
       dec=planet.dec,
       style=<your style>,
       label=planet.name,
     )

What other types of objects would you like to do this for? I ask that, cause maybe some of the starplot models can be improved to support your use case. Adding a model for comets is still on my to-do list :)

An interface to the plot object where I would pass a list of RAs and DECs and have it return a list of x,y locations that could then be passed directly to the matplotlib plot function without a further transformation. My code would be responsible for all the styling (color, symbol, line widths, etc.)

One new thing I documented in the new version (v0.16) is the ax attribute of each plot instance, which is the underlying matplotlib axes object that everything is plotted on. You can plot things directly to that in axes coordinates.

Ohhh, maybe you're also asking for a general utility function that converts RA/DEC to axes coordinates of the plot? That would be useful. It does already exist in most (or all) plot types, just not documented and could probably use some clean up :) I'll put this on the roadmap for version 0.18 -- when I plan to make a lot of coordinate system improvements

[sizzzzlerz]

thanks, Steve! I totally missed the planets module. That's exactly what I wanted to do and more. In addition to the planets, I also want to plot other celestial objects such as asteroids and comets. Basically, anything for which orbital parameters are available. This also includes man-made objects like ISS, Hubble, or other satellites. This is a great start. Larry

…

On Tue, Sep 9, 2025 at 6:27 AM Steve Berardi ***@***.***> wrote: *steveberardi* left a comment (steveberardi/starplot#164) <#164 (comment)> For the planets, one thing you can do (that exists today in Starplot) is iterate through the days you want to show the planet positions, and then get Planet instances for each day <https://starplot.dev/reference-models/#starplot.Planet.get> and plot them as markers. Here's some pseudocode: p = <your plot instance> for dt in dates: for planet in Planet.all(dt): p.marker( ra=planet.ra, dec=planet.dec, style=<your style>, label=planet.name, ) What other types of objects would you like to do this for? I ask that, cause maybe some of the starplot models can be improved to support your use case. Adding a model for comets is still on my to-do list :) An interface to the plot object where I would pass a list of RAs and DECs and have it return a list of x,y locations that could then be passed directly to the matplotlib plot function without a further transformation. My code would be responsible for all the styling (color, symbol, line widths, etc.) One new thing I documented in the new version (v0.16) is the ax attribute of each plot instance <https://starplot.dev/reference-mapplot/#starplot.MapPlot.ax>, which is the underlying matplotlib axes object that everything is plotted on. You can plot things directly to that in axes coordinates. Ohhh, maybe you're also asking for a general utility function that converts RA/DEC to axes coordinates of the plot? That would be useful. It does already exist in most (or all) plot types, just not documented and could probably use some clean up :) I'll put this on the roadmap for version 0.18 -- when I plan to make a lot of coordinate system improvements — Reply to this email directly, view it on GitHub <#164 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AARIBSYERRW5GJPOI2B2CN33R3IULAVCNFSM6AAAAACF7KOAH6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTENZQG42TAMZSGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[steveberardi]

ah, I hadn't thought of adding man-made satellites to Starplot before, but I definitely see the value there (especially for horizon plots) and it looks like it'd be pretty easy to add with the help of Skyfield, and if the user supplies a TLE. I'll put something on the roadmap for this. Thanks for the suggestion!

[sizzzzlerz]

As a follow-up, I modified one of the example programs so as to plot the location of the Sun at the beginning of each month of the year using Sun.get to compute the RA/DEC and marker to display the sun symbol with a label. See the attached image. You'll notice that the label is missing from 3 of the months, Feb, Mar, and Jul. Debugging this code, I discovered that there is a flag to inhibit plotting the label text if the text overlaps with constellation lines and that is happening in each of these months. The problem is there is no way to override this flag even though the mechanism to do so is there through the use of kwargs. Unfortunately, the argument list to marker does not include kwargs even though functions it, in turn, calls do. One of these arguments is the collision flag for constellation lines, remove_on_constellation_collision.

Was not having kwargs as a marker function argument a design decision or just an oversight? In any case, without a mechanism for setting this flag making plotting marker labels problematical.

[steveberardi]

Yeah, the code (and documentation) around the label collision handling could definitely be improved. In some cases you can do something like:

p = <your plot intance>
p.hide_colliding_labels = False     # turn OFF collision handling
p.marker(...)                       # plot your marker
p.hide_colliding_labels = True      # turn ON collision handling

That hide_colliding_labels attribute only controls collisions with other labels though, so this won't work in your case.

I reviewed the code, and I think one way you can get around this for now is plot the marker and text separately. For example:

p.marker(..., label=None)   # label will not be plotted if it's None
p.text(
  text="your label",
  ra,
  dec,
  style,
  hide_on_collision=False,
  remove_on_constellation_collision=False,   # this will allow collisions with constellations
)

That last kwarg remove_on_constellation_collision isn't documented, but unlike the marker function, any kwargs you pass to text will get passed to the underlying text plotting method which uses remove_on_constellation_collision

I'll put something on the roadmap to clean this up! 🧹 😄

[mjrfringes]

Perhaps a related request: is it already possible to add a polygon (e.g. for an instrument's field of view or footprint on sky, with vertices in ra/dec) on the plot? And if so, do you have an example for this?

I would like to overlay a series of these polygons to show how to tile a region of the sky with an instrument. Thanks!

[steveberardi]

@mjrfringes yeah, there's a polygon function available on all plot types.

What type of instrument are you looking to plot the FOV for? If it's a scope or camera, then there's an optic_fov function that might help. If it's some other type of instrument, let me know and I'll think about adding support for it, or maybe just add a generic optic with only a user-defined FOV.