Ok, it's much simpler than it seems, but extremely important if you want to work with x,y,z and define angles.
In the celestial sphere astronomers define the celestial equator (a projection of Earth's equator) and the ecliptic, which is the apparent motion of the Sun through the sphere during the year. Of course, the ecliptic is basically a projection of Earth's orbit into the apparent sphere, so when we say "the ecliptic plane" we mean the plane of our orbit.
The point where the ecliptic and the celestial equator intersect is the vernal equinox (Northern Hemisphere seasons). On March 21st this is the apparent position of the Sun in the sky. The line between this point and Earth's center is also the intersection between the equatorial plane and the ecliptic plane.
The geocentric-equatorial reference frame has the origin on Earth's center, the Z axis through the North pole, the X axis pointing to the vernal equinox, and the Y axis follows the right hand rule. Both X and Y will be on the plane of the equator. X will also happen to be on the ecliptic plane, but not Y.
The heliocentric-ecliptic reference frame has the origin on the Sun's center, the X axis pointing to the vernal equinox, the Y axis 90º ahead in the direction of Earth's orbit, and the Z axis pointing North perpendicular to the equatorial plane (it's not coincident with the Sun's North pole).
The perifocal coordinate system makes the XY plane coincident with the satellite's orbit. The X axis points to the periapsis, the Y axis is 90º ahead in the direction of its motion and the Z axis completes the right hand rule.
Source for the 3 above:
Fundamentals of Astrodynamics by Bate, Mueller and White; ISBN 0-486-60061-0.
I haven't found a geocentric-ecliptic frame in bibliography, but I have used it and I'm sure it does exist. Basically it's centered on Earth, X axis to the vernal equinox, Z axis pointing North perpendicular to the ecliptic plane and the Y axis completes the right hand rule.
If you use geocentric-ecliptic and heliocentric-ecliptic there's a nice simplification as the XY plane is coincident, so you just have to add angles to convert from one to the other. The perifocal frame doesn't have this property so you need a rotation to convert, but it's nice because you only need one angle to describe your satellite's position.
Are you familiar with
Spherical coordinate systems? I assume yes because you have used trigonometry in your code, if not you'll be able to understand it.
So when you use 3d vectors and x,y,z variables you must know what reference frame they refer to. I think that's all you need to do the conversions, though you may need a pen and a paper to draw some arrows and angles before you understand everything.
