asterion-solver 0.4.0__py3-none-win_amd64.whl

asterion/__init__.py

@@ -0,0 +1,41 @@
+# Copyright 2026 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+Asterion Solver, a fast blind astrometric plate solver: finds the celestial coordinates, scale and orientation of
+images which are in memory, such as the frames of a camera.
+
+    import asterion
+
+    asterion.install_catalog("tycho2")          # once per machine
+
+    with asterion.Solver() as solver:           # the catalogs stay open between solves
+        result = solver.solve(frame)            # a 2D array of gray levels
+        if result.solved:
+            print(result.ra, result.dec, result.scale)
+"""
+from importlib import metadata as _metadata
+
+from ._catalogs import (Catalog, InstallationCancelled, Progress, catalogs, default_catalog_directory, install_catalog,
+                        version)
+from ._native import AsterionError
+from ._solver import DeepSkyObject, Match, Result, Solver
+
+try:
+    __version__ = _metadata.version("asterion-solver")
+except _metadata.PackageNotFoundError:
+    # not installed: the sources
+    __version__ = "unknown"
+
+__all__ = ["AsterionError", "Catalog", "DeepSkyObject", "InstallationCancelled", "Match", "Progress", "Result", "Solver",
+           "catalogs", "default_catalog_directory", "install_catalog", "version"]

asterion/_catalogs.py

@@ -0,0 +1,183 @@
+# Copyright 2026 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""The catalogs of stars, which Asterion installs once on a machine."""
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional, Union
+
+from . import _native
+from ._native import AsterionError
+
+PathLike = Union[str, bytes, os.PathLike]
+
+
+class InstallationCancelled(AsterionError):
+    """The progress callback stopped the installation of a catalog. Installing it again resumes it."""
+
+
+InstallationCancelled.__module__ = "asterion"
+
+
+@dataclass(frozen=True)
+class Catalog:
+    """
+    A catalog: one which can be installed, or one which is installed in a directory. The numbers of the index are
+    None when it isn't installed.
+
+    Attributes:
+        name: its name, such as "gaia-500", or the one of its index file, without .astx
+        description: what it is, and the fields of view it's for, or "" if Asterion doesn't know it
+        installed: whether it's installed in the directory
+        available: whether install_catalog can install it
+        size: the size of its index file, in bytes
+        stars: the number of stars of its index
+        quads: the number of quads of its index, the patterns of stars it searches for
+        magnitude_limit: the magnitude of its faintest stars
+        min_quad_arcmin: the size of its smallest quads, in arcminutes
+        max_quad_deg: the size of its largest quads, in degrees
+        error: why its index file can't be read, or None
+    """
+
+    name: str
+    description: str
+    installed: bool
+    available: bool
+    size: Optional[int]
+    stars: Optional[int]
+    quads: Optional[int]
+    magnitude_limit: Optional[float]
+    min_quad_arcmin: Optional[float]
+    max_quad_deg: Optional[float]
+    error: Optional[str]
+
+
+@dataclass(frozen=True)
+class Progress:
+    """
+    An event of the installation of a catalog, the ones of asterion --download-catalog --json.
+
+    Attributes:
+        event: "step" when a step starts, "progress" when it made progress, "detail" when it did something worth
+            telling, "done" when it's over, whether it succeeded or failed, or "info" for what isn't part of a step
+        step: what the step does, for people, such as "Downloading gaia-500 (1,234 MB)", or None for "info"
+        unit: the unit of the work of the step, in plural form, such as "MB"
+        completed: the units of work done since the step started
+        total: the units of work of the step, or None if it isn't known
+        fraction: the part of the step which is done, from 0 to 1, or None if it isn't known
+        bytes: the bytes transferred since the step started, or None if the step transfers no data
+        message: the message of the "detail" and "info" events
+    """
+
+    event: str
+    step: Optional[str]
+    unit: Optional[str]
+    completed: int
+    total: Optional[int]
+    fraction: Optional[float]
+    bytes: Optional[int]
+    message: Optional[str]
+
+
+def version() -> str:
+    """The version of the library, such as "0.4.0"."""
+    return _native.string("asterion_version")
+
+
+def default_catalog_directory() -> Path:
+    """The directory of the catalogs which the functions use by default: $ASTERION_CATALOGS, or ~/.asterion/catalogs,
+    the one of the command line tool."""
+    return Path(_native.string("asterion_default_catalog_directory"))
+
+
+def catalogs(directory: Optional[PathLike] = None) -> list[Catalog]:
+    """The catalogs which can be installed, then the other ones which are installed in a directory, by default the one
+    of the command line tool."""
+    directory = _native.path(directory)
+    count = _native.check(_native.call("asterion_catalogs", directory, None, 0))
+    described = (_native.Catalog * count)()
+    # an index file may have been removed meanwhile
+    count = min(count, _native.check(_native.call("asterion_catalogs", directory, described, count)))
+    return [_catalog(catalog) for catalog in described[:count]]
+
+
+def install_catalog(name: str, directory: Optional[PathLike] = None,
+                    progress: Optional[Callable[[Progress], Optional[bool]]] = None) -> None:
+    """
+    Installs a catalog, such as "tycho2" or "gaia-500", the way asterion --download-catalog does, and returns when
+    it's over. An interrupted installation resumes its download the next time. Ctrl-C cancels it, between two events
+    of its progress. A solver which uses the catalog must be closed before installing it again.
+
+    Args:
+        name: the name of the catalog, as catalogs() lists them
+        directory: the directory of the catalogs, by default the one of the command line tool
+        progress: receives the progress, on the calling thread: returning True cancels the installation, which raises
+            InstallationCancelled. An exception of the callback, such as KeyboardInterrupt, cancels it too, and is
+            raised once the installation stopped.
+
+    Raises:
+        InstallationCancelled: if the callback cancelled the installation
+        AsterionError: if the catalog is unknown, or can't be installed
+    """
+    failure = None
+
+    def receive(event, user_data):
+        # Python code which runs during the installation: KeyboardInterrupt is raised there
+        nonlocal failure
+        try:
+            return 1 if progress is not None and progress(_progress(event.contents)) else 0
+        except BaseException as e:
+            failure = e
+            return 1
+
+    # the callback must stay referenced while the library may call it
+    callback = _native.ProgressCallback(receive)
+    status = _native.call("asterion_install_catalog", _native.path(directory), name.encode("utf-8"), callback, None)
+    if failure is not None:
+        raise failure
+    if status == _native.CANCELLED:
+        raise InstallationCancelled(f"The installation of {name} was cancelled")
+    _native.check(status)
+
+
+def _catalog(catalog):
+    def number(value):
+        return _native.optional(value) if catalog.installed else None
+
+    return Catalog(
+        name=_native.text(catalog.name),
+        description=_native.text(catalog.description),
+        installed=bool(catalog.installed),
+        available=bool(catalog.available),
+        size=catalog.size if catalog.installed else None,
+        stars=catalog.stars if catalog.installed else None,
+        quads=catalog.quads if catalog.installed else None,
+        magnitude_limit=number(catalog.magnitude_limit),
+        min_quad_arcmin=number(catalog.min_quad_arcmin),
+        max_quad_deg=number(catalog.max_quad_deg),
+        error=_native.text(catalog.error) or None,
+    )
+
+
+def _progress(event):
+    return Progress(
+        event=_native.EVENTS.get(event.event, str(event.event)),
+        step=_native.text(event.step),
+        unit=_native.text(event.unit),
+        completed=event.completed,
+        total=event.total if event.total >= 0 else None,
+        fraction=_native.optional(event.fraction),
+        bytes=event.bytes if event.bytes >= 0 else None,
+        message=_native.text(event.message),
+    )

asterion/_native.py

@@ -0,0 +1,259 @@
+# Copyright 2026 the original author or authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+The native library: the structures and the functions of asterion.h, and the GraalVM isolate in which the
+library runs. The isolate is created the first time the library is used, and each Python thread which
+calls the library is attached to it.
+"""
+import ctypes as c
+import math
+import os
+import sys
+import threading
+from pathlib import Path
+
+
+class AsterionError(Exception):
+    """An error which the library reports, with its message."""
+
+
+AsterionError.__module__ = "asterion"
+
+
+# The structures of asterion.h, field by field: ASTERION_MAX_SIP_ORDER and ASTERION_MAX_SIP_INVERSE_ORDER
+_SIP = c.c_double * 6 * 6
+_SIP_INVERSE = c.c_double * 8 * 8
+
+
+class Options(c.Structure):
+    _fields_ = [(name, c.c_double) for name in
+                ("ra", "dec", "radius", "scale_low", "scale_high", "fov", "pixel_size", "timeout", "sigma", "epoch")] + \
+               [(name, c.c_int32) for name in ("parity", "sip_order", "binning", "max_stars", "quad_stars", "padding")]
+
+
+class Solution(c.Structure):
+    _fields_ = [(name, c.c_double) for name in
+                ("ra", "dec", "scale", "rotation", "field_width", "field_height", "rms", "log_odds", "focal_length",
+                 "pixel_size", "fwhm_pixels", "fwhm_arcsec")] + \
+               [("crpix", c.c_double * 2), ("crval", c.c_double * 2), ("cd", c.c_double * 4),
+                ("sip_a", _SIP), ("sip_b", _SIP), ("sip_ap", _SIP_INVERSE), ("sip_bp", _SIP_INVERSE),
+                ("read_ms", c.c_double), ("detect_ms", c.c_double), ("solve_ms", c.c_double)] + \
+               [(name, c.c_int32) for name in ("sip_order", "sip_inverse_order", "flipped", "matched_stars", "stars")] + \
+               [("index", c.c_char * 64), ("padding", c.c_int32)]
+
+
+class Object(c.Structure):
+    _fields_ = [(name, c.c_double) for name in
+                ("ra", "dec", "x", "y", "distance", "major_arcmin", "minor_arcmin", "angle", "magnitude")] + \
+               [("messier", c.c_int32), ("name", c.c_char * 32), ("designation", c.c_char * 32),
+                ("common_name", c.c_char * 128), ("aliases", c.c_char * 256), ("type", c.c_char * 32)]
+
+
+class Match(c.Structure):
+    _fields_ = [(name, c.c_double) for name in ("x", "y", "ra", "dec", "residual")]
+
+
+class Catalog(c.Structure):
+    _fields_ = [("name", c.c_char * 64), ("description", c.c_char * 256), ("installed", c.c_int32), ("available", c.c_int32),
+                ("size", c.c_int64), ("stars", c.c_int64), ("quads", c.c_int64), ("magnitude_limit", c.c_double),
+                ("min_quad_arcmin", c.c_double), ("max_quad_deg", c.c_double), ("error", c.c_char * 256)]
+
+
+class Progress(c.Structure):
+    _fields_ = [("event", c.c_int32), ("padding", c.c_int32), ("completed", c.c_int64), ("total", c.c_int64),
+                ("bytes", c.c_int64), ("fraction", c.c_double), ("step", c.c_char_p), ("unit", c.c_char_p),
+                ("message", c.c_char_p)]
+
+
+ProgressCallback = c.CFUNCTYPE(c.c_int, c.POINTER(Progress), c.c_void_p)
+
+UINT8, UINT16, FLOAT32 = 1, 2, 3
+SOLVED, NOT_SOLVED, ERROR, CANCELLED = 1, 0, -1, -2
+PARITIES = {"both": 0, "normal": 1, "flipped": 2}
+EVENTS = {1: "step", 2: "progress", 3: "detail", 4: "done", 5: "info"}
+
+_STRUCTURES = {"asterion_options": Options, "asterion_solution": Solution, "asterion_object": Object,
+               "asterion_match": Match, "asterion_catalog": Catalog, "asterion_progress": Progress}
+
+_p = c.c_void_p
+_SIGNATURES = {
+    "graal_create_isolate": (c.c_int, [_p, c.POINTER(_p), c.POINTER(_p)]),
+    "graal_attach_thread": (c.c_int, [_p, c.POINTER(_p)]),
+    "graal_detach_thread": (c.c_int, [_p]),
+    "asterion_version": (c.c_int, [_p, c.c_char_p, c.c_size_t]),
+    "asterion_default_catalog_directory": (c.c_int, [_p, c.c_char_p, c.c_size_t]),
+    "asterion_catalogs": (c.c_int, [_p, c.c_char_p, c.POINTER(Catalog), c.c_int]),
+    "asterion_install_catalog": (c.c_int, [_p, c.c_char_p, c.c_char_p, ProgressCallback, _p]),
+    "asterion_open": (c.c_int, [_p, c.c_char_p, c.POINTER(_p)]),
+    "asterion_close": (c.c_int, [_p, _p]),
+    "asterion_default_options": (c.c_int, [_p, c.POINTER(Options)]),
+    "asterion_solve": (c.c_int, [_p, _p, _p, c.c_int, c.c_int, c.c_int, c.c_longlong, c.c_int, c.POINTER(Options),
+                                 c.POINTER(Solution), c.POINTER(_p)]),
+    "asterion_result_free": (None, [_p, _p]),
+    "asterion_result_json": (c.c_int, [_p, _p, c.c_char_p, c.c_size_t]),
+    "asterion_result_object_count": (c.c_int, [_p, _p]),
+    "asterion_result_object": (c.c_int, [_p, _p, c.c_int, c.POINTER(Object)]),
+    "asterion_result_match_count": (c.c_int, [_p, _p]),
+    "asterion_result_match": (c.c_int, [_p, _p, c.c_int, c.POINTER(Match)]),
+    "asterion_result_pixel_to_sky": (c.c_int, [_p, _p, c.c_double, c.c_double, c.POINTER(c.c_double), c.POINTER(c.c_double)]),
+    "asterion_result_sky_to_pixel": (c.c_int, [_p, _p, c.c_double, c.c_double, c.POINTER(c.c_double), c.POINTER(c.c_double)]),
+    "asterion_error": (c.c_int, [_p, c.c_char_p, c.c_size_t]),
+    "asterion_sizeof": (c.c_int, [_p, c.c_char_p]),
+}
+
+
+def _library_file():
+    """The library next to this module, or the one which ASTERION_LIBRARY names, to use another build."""
+    configured = os.environ.get("ASTERION_LIBRARY")
+    if configured:
+        return configured
+    name = {"win32": "libasterion.dll", "darwin": "libasterion.dylib"}.get(sys.platform, "libasterion.so")
+    return str(Path(__file__).with_name(name))
+
+
+class _Attachment:
+    """The thread of the isolate of a Python thread, which is detached when the Python thread ends."""
+
+    def __init__(self, library, thread):
+        self.library = library
+        self.thread = thread
+        self.ident = threading.get_ident()
+        self.pid = os.getpid()
+
+    def __del__(self):
+        # Python releases the thread-local data of a thread when it ends, on that thread: a thread can only detach
+        # itself. A forked process has a copy of the isolate, without its threads, which it must not touch. At exit,
+        # the library may be gone already
+        if threading.get_ident() == self.ident and os.getpid() == self.pid:
+            try:
+                self.library.graal_detach_thread(self.thread)
+            except Exception:
+                pass
+
+
+class _Isolate:
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._library = None
+        self._isolate = None
+        self._forked = False
+        self._local = threading.local()
+        if hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=self._after_fork)
+
+    def _after_fork(self):
+        # the isolate of the parent can't be used, and the lock may have been held by one of its threads
+        self._lock = threading.Lock()
+        self._forked = self._library is not None
+
+    def usable(self):
+        """Whether the library can be called: it's loaded, and this process isn't a fork of the one which loaded it."""
+        return self._library is not None and not self._forked
+
+    def thread(self):
+        """The library, and the thread of the isolate of the calling thread, attached the first time."""
+        if self._forked:
+            raise AsterionError("The library can't be used in a process forked after it was started: "
+                                "start the processes with multiprocessing.set_start_method('spawn')")
+        attachment = getattr(self._local, "attachment", None)
+        if attachment is not None:
+            return self._library, attachment.thread
+        with self._lock:
+            if self._library is None:
+                self._create()
+                return self._library, self._local.attachment.thread
+        thread = c.c_void_p()
+        if self._library.graal_attach_thread(self._isolate, c.byref(thread)) != 0:
+            raise AsterionError("Unable to attach the thread to the isolate of the library")
+        # a finalizer which ran meanwhile, on this thread, may have attached it already: to the same isolate thread
+        attachment = getattr(self._local, "attachment", None)
+        if attachment is None:
+            attachment = self._local.attachment = _Attachment(self._library, thread)
+        return self._library, attachment.thread
+
+    def _create(self):
+        library = c.CDLL(_library_file())
+        for name, (result, arguments) in _SIGNATURES.items():
+            function = getattr(library, name)
+            function.restype, function.argtypes = result, arguments
+        isolate, thread = c.c_void_p(), c.c_void_p()
+        if library.graal_create_isolate(None, c.byref(isolate), c.byref(thread)) != 0:
+            raise AsterionError("Unable to create the isolate of the library")
+        for name, structure in _STRUCTURES.items():
+            if library.asterion_sizeof(thread, name.encode()) != c.sizeof(structure):
+                raise AsterionError(f"{name} doesn't match the library {_library_file()}")
+        self._library, self._isolate = library, isolate
+        self._local.attachment = _Attachment(library, thread)
+
+
+_ISOLATE = _Isolate()
+
+
+def call(name, *arguments):
+    """Calls a function of the library on the thread of the caller, which it receives first."""
+    library, thread = _ISOLATE.thread()
+    return getattr(library, name)(thread, *arguments)
+
+
+def release(name, handle):
+    """Releases a handle when its object is garbage collected, which may happen at exit, or in a forked process:
+    nothing is reported, as nobody can handle it."""
+    if _ISOLATE.usable():
+        try:
+            call(name, handle)
+        except Exception:
+            pass
+
+
+def error():
+    """The message of the last error of the calling thread."""
+    return string("asterion_error")
+
+
+def check(status):
+    """The status of a call, or AsterionError with its message if it failed."""
+    if status == ERROR:
+        raise AsterionError(error())
+    return status
+
+
+def string(name, *arguments):
+    """A string which a function copies to a buffer: the function tells the size it needs, if the first one is
+    too small."""
+    buffer = c.create_string_buffer(4096)
+    length = call(name, *arguments, buffer, len(buffer))
+    if length < 0 and name != "asterion_error":
+        raise AsterionError(error())
+    if length >= len(buffer):
+        buffer = c.create_string_buffer(length + 1)
+        call(name, *arguments, buffer, len(buffer))
+    return buffer.value.decode("utf-8", errors="replace")
+
+
+def path(directory):
+    """A directory for the library, UTF-8 encoded, or None for the default one."""
+    if directory is None:
+        return None
+    directory = os.fspath(directory)
+    return directory if isinstance(directory, bytes) else directory.encode("utf-8")
+
+
+def text(value):
+    """A string of a structure, or of a progress event."""
+    return value.decode("utf-8", errors="replace") if value is not None else None
+
+
+def optional(value):
+    """A number of a structure, where NAN means unknown: None."""
+    return None if math.isnan(value) else value