gergely/swe-glib
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Restructure README file

Browse Source
This commit is contained in:
Gergely Polonkai 2015-09-02 14:26:17 +00:00
parent 5dc7240420
commit d87f5e98f7
1 changed files with 59 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
README.md
View File

@ -1,22 +1,34 @@
# SWE-GLib # SWE-GLib
SWE-GLib is a GLib style wrapper library around Astrodienst's [Swiss Ephemeris library](http://www.astro.com/swisseph/). SWE-GLib is a GLib style wrapper library around Astrodienst's
[Swiss Ephemeris library](http://www.astro.com/swisseph/).
The source tree contains Astrodienst's ephemeride files, as requested by Alois Treindl of Astrodienst in a mail written to me on 24 July, 2013. The source tree contains Astrodienst's ephemeride files, as requested
by Alois Treindl of Astrodienst in a mail written to me on 24 July,
2013.
## GTK-Doc ## GTK-Doc
The project utilizes [GTK-Doc](http://www.gtk.org/gtk-doc/), requiring version 1.19 or later. Although the generated documentation is a bit messy (not everything is documented, and there are some unresolved variables, like [SERVER] on the generated index page. The project utilizes [GTK-Doc](http://www.gtk.org/gtk-doc/), requiring
version 1.19 or later. Although the generated documentation is a bit
messy (not everything is documented, and there are some unresolved
variables, like [SERVER] on the generated index page.
Still, the documentation generates well, and at least gives a clue about object usage. Still, the documentation generates well, and at least gives a clue
about object usage.
## Bindings ## Bindings
SWE-GLib utilizes [GObject Introspection](https://wiki.gnome.org/GObjectIntrospection), which means it is available for many languages. Check out the [examples](examples) directory for some sample code! SWE-GLib utilizes
[GObject Introspection](https://wiki.gnome.org/GObjectIntrospection),
which means it is available for many languages. Check out the
[examples](examples) directory for some sample code!
## Usage ## Usage
Many functions return non-opaque C structs; their documentation can be found inline, and in the generated GTK-Doc. Unless otherwise stated, the returned values should never be freed. Many functions return non-opaque C structs; their documentation can be
found inline, and in the generated GTK-Doc. Unless otherwise stated,
the returned values should never be freed.
### Creating the required objects ### Creating the required objects
@ -67,11 +79,13 @@ GList *sun_aspects = gswe_moment_get_planet_aspects(moment, GSWE_PLANET_SUN);
GList *sun_antiscia = gswe_moment_get_planet_antiscia(moment, GSWE_PLANET_SUN); GList *sun_antiscia = gswe_moment_get_planet_antiscia(moment, GSWE_PLANET_SUN);
``` ```
The returned GList objects hold zero or more `GsweAspectData` or `GsweAntiscionData` objects, respectively. The returned GList objects hold zero or more `GsweAspectData` or
`GsweAntiscionData` objects, respectively.
### Getting the Moon phase ### Getting the Moon phase
Last, but not least, SWE-GLib can calculate Moon's phase at the given moment. For that, you have to call `gswe_moment_get_moon_phase()`: Last, but not least, SWE-GLib can calculate Moon's phase at the given
moment. For that, you have to call `gswe_moment_get_moon_phase()`:
```c ```c
GsweMoonPhaseData *moon_phase = gswe_moment_get_moon_phase(moment); GsweMoonPhaseData *moon_phase = gswe_moment_get_moon_phase(moment);
@ -79,34 +93,60 @@ GsweMoonPhaseData *moon_phase = gswe_moment_get_moon_phase(moment);
### About altitude ### About altitude
The Swiss Ephemeris library requires the altitude value to be specified for several calculations. It also notifies how important it is: The Swiss Ephemeris library requires the altitude value to be
specified for several calculations. It also notifies how important it
is:
> the altitude above sea must be in meters. Neglecting the altitude can result in an error of about 2 arc seconds with the moon and at an altitude 3000m. > the altitude above sea must be in meters. Neglecting the altitude
> can result in an error of about 2 arc seconds with the moon and at
> an altitude 3000m.
2 arc seconds is about 0.000555 degrees of error, which is, well, kind of small. Of course, if you need very precise horoscopes or need planetary positions for a totally different thing, you should really provide a (close to) exact value; otherwise, it is safe to pass any value (well, which seems logical: the average level of all dry lands is about 840 meters; the average level of the whole planet Earth (including oceans and seas) is around 280 meters. Providing a value of ~400 should be OK most of the time). 2 arc seconds is about 0.000555 degrees of error, which is, well, kind
of small. Of course, if you need very precise horoscopes or need
planetary positions for a totally different thing, you should really
provide a (close to) exact value; otherwise, it is safe to pass any
value (well, which seems logical: the average level of all dry lands
is about 840 meters; the average level of the whole planet Earth
(including oceans and seas) is around 280 meters. Providing a value of
~400 should be OK most of the time).
## API stability ## API stability
The project is currently transitioning to 2.0. master is a bit fragile at the moment, 1.x versions are considered to be stable (although see commit 8f52aba about a huge typo-bug). The project is currently transitioning to 2.0. master is a bit fragile
at the moment, 1.x versions are considered to be stable (although see
commit 8f52aba about a huge typo-bug).
## Limitations ## Limitations
### Topocentric calculations only ### Topocentric calculations only
Although the original Swiss Ephemeris library supports it, SWE-GLib can't do Heliocentric, nor Geocentric (as seen from the center of Earth) calculations, only Topocentric (as seen from a given point on Earth"s surface) calculations yet. Although the original Swiss Ephemeris library supports it, SWE-GLib
can't do Heliocentric, nor Geocentric (as seen from the center of
Earth) calculations, only Topocentric (as seen from a given point on
Earth’s surface) calculations yet.
### Database size ### Database size
The size of all data files provided by Astrodienst is around 40MB. Although it should not be a problem with today's home hardware, it can be a hard requirement on embedded systems. For basic calculations, keeping the following files under $(datadir)/swe-glib is usually enough: The size of all data files provided by Astrodienst is around
40MB. Although it should not be a problem with today's home hardware,
it can be a hard requirement on embedded systems. For basic
calculations, keeping the following files under $(datadir)/swe-glib is
usually enough:
* seas_18.se1 * `seas_18.se1`
* semo_18.se1 * `semo_18.se1`
* sepl_18.se1 * `sepl_18.se1`
### Fixed stars are not known yet ### Fixed stars are not known yet
Although Swiss Ephemeris has the functionality to calculate the position of fixed stars, SWE-GLib doesn't provide such functionality. This, however, is a planned feature for the close future. Although Swiss Ephemeris has the functionality to calculate the
position of fixed stars, SWE-GLib doesn't provide such
functionality. This, however, is a planned feature for the close
future.
## Licencing ## Licencing
As the underlying Swiss Ephemeris is published under GPL (or a commercial license I can not afford), SWE-GLib is also uses that. This means that you can currently use SWE-GLib in software published under the GNU GPL v3. As the underlying Swiss Ephemeris is published under GPL (or a
commercial license I can not afford), SWE-GLib is also uses that. This
means that you can currently use SWE-GLib in software published under
the GNU GPL v3 (or, at your option, any later version).