demeteor 0.1.0__tar.gz

demeteor-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: demeteor
+Version: 0.1.0
+Summary: A collection of utility functions for all-sky and spectral meteor cameras
+Author: Martin Odokienko
+Author-email: martin.balaz@fmph.uniba.sk
+Requires-Python: >=3.11,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: astropy
+Requires-Dist: dotmap
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyyaml
+Requires-Dist: scipy
+Description-Content-Type: text/markdown
+
+

demeteor-0.1.0/demeteor/catalogue/__init__.py

@@ -0,0 +1 @@
+from .catalogue import Catalogue

demeteor-0.1.0/demeteor/catalogue/catalogue.py

@@ -0,0 +1,177 @@
+import datetime
+from typing import Any, Optional
+
+import numpy as np
+import pandas as pd
+
+from pathlib import Path
+
+from astropy.coordinates import EarthLocation, FK5, SkyCoord, AltAz, get_body, concatenate, Angle
+from astropy.time import Time
+from astropy import units as u
+
+
+class Catalogue:
+    PLANETS = ['mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune']
+
+    def __init__(self, filename: Path = None):
+        self._populated = False
+        self.planets = []
+        self.planets_skycoord = None
+
+        if filename is not None:
+            self._populated = True
+            self.stars = pd.read_csv(filename, sep='\t', header=1)
+            self.stars_skycoord = SkyCoord(self.stars.ra.to_numpy() * u.deg,
+                                           self.stars.dec.to_numpy() * u.deg,
+                                           frame=FK5(equinox=Time('J2000')))
+        else:
+            self.stars = []
+
+        self._mask = np.ones(shape=len(self.stars) + len(self.PLANETS), dtype=bool)
+
+    @property
+    def populated(self) -> bool:
+        return self._populated
+
+    def build_planets(self,
+                      location: EarthLocation,
+                      time: Time = None):
+        if time is None:
+            time = Time(datetime.datetime.now(tz=datetime.UTC))
+
+        sun = get_body('sun', time=time, location=location)
+
+        planets = pd.DataFrame(columns=self.stars.columns)
+
+        index = len(self.stars)
+        for name in self.PLANETS:
+            body = get_body(name, time=time, location=location)
+            sundist = body.hcrs.distance
+            phase = body.separation(sun)
+            new_planet = pd.DataFrame(
+                data=[
+                    [
+                        body.ra.degree,
+                        body.dec.degree,
+                        body.distance.to(u.lightyear).value,
+                        self.planet_brightness(name, body.distance, sundist, phase),
+                        -10
+                    ]
+                ],
+                columns=self.stars.columns,
+                index=[index]
+            )
+            if len(planets) > 0:
+                planets = pd.concat([planets, new_planet])
+                index += 1
+            else:
+                planets = new_planet
+
+        self.planets = planets
+        self.planets_skycoord = SkyCoord(planets.ra.to_numpy() * u.deg,
+                                         planets.dec.to_numpy() * u.deg,
+                                         frame=FK5(equinox=Time('J2000')))
+
+    def radec(self,
+              location: EarthLocation,
+              time: Time = None,
+              *,
+              planets: bool = True,
+              masked: bool) -> SkyCoord:
+        if self._populated:
+            if time is None:
+                time = Time(datetime.datetime.now(tz=datetime.UTC))
+
+            if planets:
+                self.build_planets(location, time)
+                total = concatenate([self.stars_skycoord, self.planets_skycoord])
+            else:
+                total = self.stars_skycoord
+
+            return total[self.mask] if masked else total
+        else:
+            return SkyCoord([] * u.rad, [] * u.rad, frame=FK5(equinox=Time('J2000')))
+
+    def altaz(self,
+              location: EarthLocation,
+              time: Time = None,
+              *,
+              planets: bool = True,
+              masked: bool) -> AltAz:
+        """
+        Return the catalogue in alt-az coordinates at `location` and at `time`.
+        Optionally include planets.
+        """
+        if time is None:
+            time = Time(datetime.datetime.now(tz=datetime.UTC))
+
+        altaz = AltAz(location=location, obstime=time, pressure=100000 * u.pascal, obswl=550 * u.nm)
+        radec = self.radec(location, time, planets=planets, masked=masked)
+        return radec.transform_to(altaz)
+
+    def vmag(self,
+             location: EarthLocation,
+             time: Time = None,
+             *,
+             masked: bool) -> np.ndarray[float]:
+        """
+        Return visual magnitudes of all objects at `location` and at `time`.
+        Optionally include planets.
+        """
+        self.build_planets(location, time)
+        vmags = pd.concat([self.stars, self.planets]).vmag.to_numpy()
+        return vmags[self.mask] if masked else vmags
+
+    @staticmethod
+    def planet_brightness(planet: str,
+                          distance_earth: u.Quantity,
+                          distance_sun: u.Quantity,
+                          phase: Angle):
+        """
+            Get the approximate visual magnitude of a planet.
+            Shamelessly stolen from APC, Montenbruck 1999
+        """
+        p = phase.degree / 100.0
+
+        match planet:
+            case 'mercury':
+                mag = -0.42 + (3.80 - (2.73 - 2 * p) * p) * p
+            case 'venus':
+                mag = -4.40 + (0.09 + (2.39 - 0.65 * p) * p) * p
+            case 'mars':
+                mag = -1.52 + 1.6 * p
+            case 'jupiter':
+                mag = -9.4 + 0.5 * p
+            case 'saturn':
+                # Currently we do not care about the rings, but it might be worth checking it later
+                sd = 0 # np.abs(np.sin(lat))
+                dl = 0 # np.abs((dlong + np.pi) % (2 * np.pi) - np.pi) / 100
+                mag = -8.88 + 2.60 * sd + 1.25 * sd**2 + 4.4 * dl
+            case 'uranus':
+                mag = -7.19
+            case 'neptune':
+                mag = -6.87
+
+        return mag + 5 * np.log10(distance_earth.to(u.au).value * distance_sun.to(u.au).value)
+
+    @property
+    def count(self) -> int:
+        return len(self.stars) + len(self.planets)
+
+    @property
+    def count_visible(self) -> int:
+        return len(self.mask[self.mask])
+
+    @property
+    def mask(self) -> np.ndarray[bool]:
+        return self._mask
+
+    @mask.setter
+    def mask(self, m: Optional[np.ndarray[bool]] = None) -> None:
+        self._mask = np.ones(shape=(self.count,), dtype=bool) if m is None else m
+        assert self.mask.shape == (self.count,), \
+            f"Mask shape does not match data shape: expected {self.count,}, got {self.mask.shape}"
+
+    def __str__(self):
+        return f"<Catalogue with {self.count_visible} / {self.count} reference objects>"

demeteor-0.1.0/demeteor/classes/loadable.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Loadable(ABC):
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        cls._registry[cls.__name__] = cls
+
+    @classmethod
+    def from_dict(cls,
+                  config: dict[str, Any]):
+        """
+        Load from a dictionary. This expects that its 'name' attribute points to the actual class in the registry.
+        """
+        return cls._registry[config['name']](**config['parameters'])
+
+    def as_dict(self):
+        """ Return a dict representation of the Projection's parameters """
+        return {
+            'name': self.__class__.__name__,
+        }
+
+    @abstractmethod
+    def _as_dict(self):
+        pass

demeteor-0.1.0/demeteor/metrics/__init__.py

@@ -0,0 +1,3 @@
+from .metrics import euclidean, spherical
+
+__all__ = [euclidean, spherical] # ToDo More to follow

demeteor-0.1.0/demeteor/metrics/metrics.py

@@ -0,0 +1,34 @@
+"""
+    All functions within this module should observe the following signature:
+    Parameters
+    ----------
+    a: np.ndarray(M, D)
+    b: np.ndarray(N, D)
+
+    Returns
+    -------
+    np.ndarray(M, N) of scalars
+"""
+
+import numpy as np
+
+from numpy.typing import NDArray
+
+
+def spherical(a: NDArray, b: NDArray) -> NDArray:
+    """
+    Compute spherical distance between a and b, each are vectors of points in two dimensions
+    """
+    return 2 * np.arcsin(
+        np.sqrt(
+            np.sin(0.5 * (b[..., 0] - a[..., 0]))**2 +
+            np.cos(a[..., 0]) * np.cos(b[..., 0]) * np.sin(0.5 * (b[..., 1] - a[..., 1]))**2
+        )
+    )
+
+
+def euclidean(a: NDArray, b: NDArray) -> NDArray:
+    """
+    Compute Euclidean distance between a and b, each are vectors of points in two dimensions
+    """
+    return np.sqrt(np.sum((a - b)**2, axis=2))

demeteor-0.1.0/demeteor/physics/atmosphere.py

@@ -0,0 +1,34 @@
+import numpy as np
+
+from . import constants
+
+from astropy import units as u
+from astropy.coordinates import Angle
+
+
+class AirMass:
+    def kasten_young(altitude: Angle,
+                     elevation: u.Quantity = 0 * u.m):
+        return np.where(
+            altitude >= 0 * u.deg,
+            AirDensity.isa(elevation) / AirDensity.isa(0 * u.m) / (np.sin(altitude) + 0.50572 * ((altitude.degree + 6.07995) ** (-1.6364))),
+            np.inf
+        )
+
+    def pickering2002(altitude: u.Quantity,
+                      elevation: u.Quantity = 0 * u.m):
+        return np.where(
+            altitude >= 0 * u.deg,
+            AirDensity.isa(elevation) / AirDensity.isa(0 * u.m) / (np.sin(altitude + np.radians(244 / (165 + 47 * altitude.degree ** 1.1)))),
+            np.inf
+        )
+
+    def attenuate(flux: u.Quantity,
+                  air_mass: u.Quantity,
+                  one: float = constants.AttenuationOneAirMassMag):
+        return np.where(air_mass <= 100, flux * np.exp(-np.log(100) / 5 * one * air_mass), 0)
+
+
+class AirDensity:
+    def isa(altitude: u.Quantity):
+        return 101325 * np.exp(-altitude.to(u.m) / (7990 * u.m)) * u.pascal

demeteor-0.1.0/demeteor/physics/constants.py

@@ -0,0 +1,3 @@
+AttenuationOneAirMassMag: float = 0.28
+AttenuationOneAirMass: float = 0.77268
+MagnitudeOneWattPerSquareMetre: float = -18.9

demeteor-0.1.0/demeteor/projections/__init__.py

@@ -0,0 +1,3 @@
+from .base import Projection
+from .equidistant import EquidistantProjection
+from .borovicka import BorovickaProjection

demeteor-0.1.0/demeteor/projections/base.py

@@ -0,0 +1,55 @@
+import dotmap
+import numpy as np
+from typing import Tuple, Any
+
+from abc import ABC, abstractmethod
+
+import yaml
+
+
+class Projection(ABC):
+    """
+    A base class for all projections. Should implement xy -> za and za -> xy conversions.
+    """
+    bounds = np.array((
+        (0, None),
+    ))
+
+    _registry = {}
+
+    def __init__(self):
+        pass
+
+    @abstractmethod
+    def __call__(self, x: np.ndarray, y: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """ Apply this projection to an array of points: xy -> za """
+
+    @abstractmethod
+    def invert(self, z: np.ndarray, a: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """ Apply an inverse projection to an array of points: za -> xy """
+
+    @abstractmethod
+    def as_dict(self) -> dict[str, float]:
+        """ Return a dict representation of the Projection's parameters """
+        pass
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        Projection._registry[cls.name] = cls
+
+    @classmethod
+    def from_dict(cls,
+                  config: dict[str, Any]):
+        return cls._registry[config['name']](**config['parameters'])
+
+    @classmethod
+    def from_dotmap(cls, dm):
+        """
+        Load from a dotmap. Useful as an intermediate step when loading from YAML.
+        """
+
+    @classmethod
+    def load(cls, file):
+        data = dotmap.DotMap(yaml.safe_load(file), _dynamic=False)
+        data = data.projection.parameters
+        return cls.from_dotmap(data)

demeteor-0.1.0/demeteor/projections/borovicka.py

@@ -0,0 +1,85 @@
+import numpy as np
+from typing import Union
+from numpy.typing import ArrayLike
+
+from .base import Projection
+from .shifters import TiltShifter
+from .transformers import BiexponentialTransformer
+from .zenith import ZenithShifter
+
+
+class BorovickaProjection(Projection):
+    """
+    Borovička all-sky projection.
+    """
+    bounds = np.array((
+        (None, None),  # x0
+        (None, None),  # y0
+        (None, None),  # a0
+        (None, None),  # A
+        (None, None),  # F
+        (0.001, None), # V
+        (None, None),  # S
+        (None, None),  # D
+        (None, None),  # P
+        (None, None),  # Q
+        (0, None),     # epsilon
+        (None, None),  # E
+    ))
+    name = 'Borovička'
+
+    def __init__(self,
+                 x0: float = 0, y0: float = 0, a0: float = 0,
+                 A: float = 0, F: float = 0,
+                 V: float = 1, S: float = 0, D: float = 0, P: float = 0, Q: float = 0,
+                 epsilon: float = 0, E: float = 0):
+        super().__init__()
+        self.axis_shifter = TiltShifter(x0=x0, y0=y0, a0=a0, A=A, F=F, E=E)
+        self.radial_transform = BiexponentialTransformer(V, S, D, P, Q)
+        self.zenith_shifter = ZenithShifter(epsilon=epsilon, E=E)
+
+    def __call__(self,
+                 x: Union[float, ArrayLike],
+                 y: Union[float, ArrayLike]) -> tuple[np.ndarray, np.ndarray]:
+        r, b = self.axis_shifter(x, y)
+        u = self.radial_transform(r)
+        z, a = self.zenith_shifter(u, b)
+        return z, a
+
+    def invert(self,
+               z: ArrayLike,
+               a: ArrayLike) -> tuple[ArrayLike, ArrayLike]:
+        if z.shape == (0,):
+            return np.empty((0,)), np.empty((0,))
+
+        u, b = self.zenith_shifter.invert(z, a)
+        r = self.radial_transform.invert(u)
+        x, y = self.axis_shifter.invert(r, b)
+        return x, y
+
+    def __str__(self):
+        return f"Borovička projection with \n" \
+               f"   {self.axis_shifter} \n" \
+               f"   {self.radial_transform} \n" \
+               f"   {self.zenith_shifter}"
+
+    def as_dict(self):
+        return self.axis_shifter.as_dict() | self.radial_transform.as_dict() | self.zenith_shifter.as_dict()
+
+    def as_tuple(self) -> tuple[float, ...]:
+        return (
+            self.axis_shifter.x0, self.axis_shifter.y0, self.axis_shifter.a0,
+            self.axis_shifter.A, self.axis_shifter.F,
+            self.radial_transform.V, self.radial_transform.S, self.radial_transform.D,
+            self.radial_transform.P, self.radial_transform.Q,
+            self.zenith_shifter.epsilon, self.zenith_shifter.E,
+        )
+
+    @classmethod
+    def from_dotmap(cls, dm):
+        return cls(
+            dm.x0, dm.y0, dm.a0,
+            dm.A, dm.F,
+            dm.V, dm.S, dm.D, dm.S, dm.Q,
+            dm.epsilon, dm.E,
+        )

demeteor-0.1.0/demeteor/projections/equidistant.py

@@ -0,0 +1,26 @@
+import numpy as np
+
+from typing import Tuple
+
+from .base import Projection
+
+
+class EquidistantProjection(Projection):
+    """ Equidistant projection that is perfectly aligned to zenith-north """
+
+    name = 'equidistant'
+
+    def __init__(self):
+        super().__init__()
+
+    def __call__(self, x: np.ndarray, y: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        z = np.sqrt(np.square(x) + np.square(y))
+        a = np.arctan2(x, -y)
+        return z, a
+
+    def invert(self, z: np.ndarray, a: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        return z * np.sin(a), z * np.cos(a)
+
+    def as_dict(self):
+        return {}
+

demeteor-0.1.0/demeteor/projections/koniferka.py

@@ -0,0 +1,98 @@
+import numpy as np
+import dotmap
+import yaml
+from typing import Union
+from numpy.typing import NDArray
+
+from .base import Projection
+from .shifters import TiltShifter
+from .transformers import SaneBiexponentialTransformer
+from .zenith import ZenithShifter
+
+
+class KoniferkaProjection(Projection):
+    """
+    Improved Borovička all-sky projection, with correct dimensions.
+    Namely,
+        r1 = 1 / D,
+        r2 = sqrt(1 / Q).
+    """
+    bounds = np.array((
+        (None, None),  # x0
+        (None, None),  # y0
+        (None, None),  # a0
+        (None, None),  # A
+        (None, None),  # F
+        (0.001, None), # V
+        (None, None),  # k_1
+        (None, None),  # p_1
+        (None, None),  # k_2
+        (None, None),  # p_2
+        (0, None),     # epsilon
+        (None, None),  # E
+    ))
+    name = 'Koniferka'
+
+    def __init__(self,
+                 x0: float = 0, y0: float = 0, a0: float = 0,
+                 A: float = 0, F: float = 0,
+                 V: float = 1, p1: float = 0, r1: float = np.inf, p2: float = 0, r2: float = np.inf,
+                 epsilon: float = 0, E: float = 0):
+        super().__init__()
+        self.axis_shifter = TiltShifter(x0=x0, y0=y0, a0=a0, A=A, F=F, E=E)
+        self.radial_transform = SaneBiexponentialTransformer(V, p1, r1, p2, r2)
+        self.zenith_shifter = ZenithShifter(epsilon=epsilon, E=E)
+
+    def __call__(self,
+                 x: Union[float, np.ndarray],
+                 y: Union[float, np.ndarray]) -> tuple[np.ndarray, np.ndarray]:
+        print("Forward")
+        print(f"{x=}, {y=}")
+        r, b = self.axis_shifter(x, y)
+        print(f"{r=}")
+        u = self.radial_transform(r)
+        print(f"{u=}, {b=}")
+        z, a = self.zenith_shifter(u, b)
+        print(f"{z=}, {a=}")
+        return z, a
+
+    def invert(self,
+               z: NDArray[np.floating],
+               a: NDArray[np.floating]) -> tuple[NDArray[np.floating], NDArray[np.floating]]:
+        print("Inverted")
+        print(f"{z=}, {a=}")
+        u, b = self.zenith_shifter.invert(z, a)
+        print(f"{u=}, {b=}")
+        r = self.radial_transform.invert(u)
+        print(f"{r=}")
+        x, y = self.axis_shifter.invert(r, b)
+        print(f"{x=}, {y=}")
+        return x, y
+
+    def __str__(self):
+        return f"Koniferka projection with \n" \
+               f"   {self.axis_shifter} \n" \
+               f"   {self.radial_transform} \n" \
+               f"   {self.zenith_shifter}"
+
+    def as_dict(self):
+        return self.axis_shifter.as_dict() | self.radial_transform.as_dict() | self.zenith_shifter.as_dict()
+
+    def as_tuple(self):
+        return (
+            self.axis_shifter.x0, self.axis_shifter.y0, self.axis_shifter.a0,
+            self.axis_shifter.A, self.axis_shifter.F,
+            self.radial_transform.V,
+            self.radial_transform.p1, self.radial_transform.r1,
+            self.radial_transform.p1, self.radial_transform.r2,
+            self.zenith_shifter.epsilon, self.zenith_shifter.E,
+        )
+
+    @classmethod
+    def from_dotmap(cls, dm):
+        return cls(
+            dm.x0, dm.y0, dm.a0,
+            dm.A, dm.F,
+            dm.V, dm.p1, dm.r1, dm.p2, dm.r2,
+            dm.epsilon, dm.E,
+        )

demeteor-0.1.0/demeteor/projections/scalers.py

@@ -0,0 +1,17 @@
+import numpy as np
+
+
+class Scaler:
+    """ Class for scaling pixels to lengths """
+
+    name = 'scaler'
+
+    def __init__(self, scale_x: float = 1, scale_y: float = 1):
+        self.scale_x = scale_x
+        self.scale_y = scale_y
+
+    def __call__(self, x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        return x * self.scale_x, y * self.scale_y
+
+    def invert(self, nx: np.ndarray, ny: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        return nx / self.scale_x, ny / self.scale_y

demeteor-0.1.0/demeteor/projections/shifters.py

@@ -0,0 +1,114 @@
+import math
+from abc import ABC, abstractmethod
+
+import numpy as np
+import scipy as sp
+from numpy.typing import ArrayLike
+
+
+class Shifter:
+    """ Shifts without scaling or rotation """
+    def __init__(self, *, x0: float = 0, y0: float = 0):
+        self.x0 = x0
+        self.y0 = y0
+
+    def __call__(self, x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        return x - self.x0, y - self.y0
+
+    def invert(self, nx: np.ndarray, ny: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        return nx + self.x0, ny + self.y0
+
+    def as_dict(self) -> dict[str, float]:
+        return dict(x=self.x0, y=self.y0)
+
+
+class ScalingShifter(Shifter):
+    """ Shifts and scales the sensor without rotation """
+    def __init__(self, *, x0: float = 0, y0: float = 0, xs: float = 1, ys: float = 1):
+        super().__init__(x0=x0, y0=y0)
+        self.xs = xs    # x scaling factor
+        self.ys = ys    # y scaling factor
+
+    def __call__(self, x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        nx, ny = super().__call__(x, y)
+        return nx * self.xs, ny * self.ys
+
+    def invert(self, nx: np.ndarray, ny: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        return super().invert(nx / self.xs, ny / self.ys)
+    
+
+class OpticalAxisShifter(Shifter):
+    """ Shifts and derotates the optical axis of the sensor """
+    def __init__(self, *, x0: float = 0, y0: float = 0, a0: float = 0, E: float = 0):
+        super().__init__(x0=x0, y0=y0)
+        self.a0 = a0                # rotation of the optical axis
+        self.E = E                  # true azimuth of the centre of FoV
+
+    def __call__(self, x: np.ndarray, y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        xs, ys = super().__call__(x, y)
+        r = np.sqrt(np.square(xs) + np.square(ys))
+        b = self.a0 - self.E + np.arctan2(ys, xs)
+        b = np.mod(b, math.tau)
+        return r, b
+
+    def invert(self, r: np.ndarray, b: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        xi = b - self.a0 + self.E
+        xs, ys = r * np.cos(xi), r * np.sin(xi)
+        x, y = super().invert(xs, ys)
+        return x, y
+
+    def __str__(self):
+        return f"<{self.__class__} x0={self.x0} y0={self.y0} a0={self.a0} E={self.E}>"
+
+    def as_dict(self):
+        return super().as_dict() | dict(
+            a0=float(self.a0),
+            E=float(self.E),
+        )
+
+
+class TiltShifter(OpticalAxisShifter):
+    """
+    Extends OpticalAxisShifter with imaging plane tilt.
+    The optical axis is tilted with respect to the sensor normal at angle A in azimuth F.
+
+    For further details see
+    Borovička (1995): A new positional astrometric method for all-sky cameras.
+    This method has been optimized for sanity
+    """
+    def __init__(self, *, x0: float = 0, y0: float = 0, a0: float = 0, A: float = 0, F: float = 0, E: float = 0):
+        super().__init__(x0=x0, y0=y0, a0=a0, E=E)
+        assert -1 <= A <= 1, f"Invalid parameter {A=}: must be -1 <= A <= 1."
+
+        self.A = A                  # imaging plane tilt, amplitude
+        self.F = F                  # imaging plane tilt, phase
+        self._phi = self.F - self.a0
+        self._cos_term = np.cos(self._phi)
+        self._sin_term = np.sin(self._phi)
+
+    def __call__(self,
+                 x: np.ndarray,
+                 y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        xs = x - self.x0
+        ys = y - self.y0
+        r, b = super().__call__(x, y)
+        r += self.A * (ys * self._cos_term - xs * self._sin_term)
+        return r, b
+
+    def invert(self,
+               r: ArrayLike,
+               b: ArrayLike) -> tuple[ArrayLike, ArrayLike]:
+        xi = b - self.a0 + self.E
+        denom = 1 + self.A * np.sin(xi - self._phi)
+        x = self.x0 + r * np.cos(xi) / denom
+        y = self.y0 + r * np.sin(xi) / denom
+        return x, y
+
+    def __str__(self) -> str:
+        return f"<{self.__class__.__name__} x0={self.x0} y0={self.y0} a0={self.a0} A={self.A} F={self.F} E={self.E}>"
+
+    def as_dict(self):
+        return super().as_dict() | dict(
+            A=float(self.A),
+            F=float(self.F),
+        )

demeteor-0.1.0/demeteor/projections/transformers.py

@@ -0,0 +1,139 @@
+from abc import ABC, abstractmethod
+import numpy as np
+import scipy as sp
+
+
+class RadialTransformer(ABC):
+    """ Class for transforming radial distances in all-sky projections """
+
+    def __call__(self, r):
+        raise NotImplementedError("Radial transformers must implement __call__(r: np.ndarray) -> np.ndarray")
+
+    @abstractmethod
+    def fprime(self, u):
+        """ Derivative function for the Newton method, not implemented in the abstract base class """
+        raise NotImplementedError("Radial transformers must implement df/dr as fprime(u: np.ndarray) -> np.ndarray")
+
+    def invert(self, u):
+        """ Numerically approximate the inverse function using the Newton method """
+        return sp.optimize.newton(lambda r: self.__call__(r) - u, np.zeros_like(u), self.fprime)
+
+
+class LinearTransformer(RadialTransformer):
+    """ Linear radial transform, u = Vr """
+
+    def __init__(self, V: float = 1):
+        assert V > 0, "Radial linear scale V must be > 0"
+        self.V = V  # radial stretch, linear coefficient
+
+    def __call__(self, r):
+        return self.V * r
+
+    def fprime(self, r):
+        """ du / dr = V """
+        return self.V * np.ones_like(r)
+
+    def as_dict(self):
+        return dict(
+            V=float(self.V),
+        )
+
+
+class ExponentialTransformer(LinearTransformer):
+    """ Linear + exponential radial correction, u = Vr + S(e^(Dr) - 1) """
+
+    def __init__(self, V: float = 1, S: float = 0, D: float = 0):
+        super().__init__(V)
+        self.S = S  # radial stretch, exponential term, linear coefficient
+        self.D = D  # radial stretch, exponential term, exponent coefficient
+
+    def __call__(self, r):
+        return super().__call__(r) + self.S * (np.exp(self.D * r) - 1)
+
+    def fprime(self, r):
+        """ du/dr = V + SDe^(Dr) """
+        return super().fprime(r) + self.S * self.D * np.exp(self.D * r)
+
+    def as_dict(self):
+        return super().as_dict() | dict(
+            S=float(self.S),
+            D=float(self.D),
+        )
+
+
+class BiexponentialTransformer(ExponentialTransformer):
+    """ Bi-exponential radial fitting procedure, u = Vr + S(e^(Dr) - 1) + P(e^(Qr^2) - 1) """
+
+    def __init__(self, V: float = 0,
+                 S: float = 0, D: float = 0,
+                 P: float = 0, Q: float = 0):
+        super().__init__(V, S, D)
+        self.P = P # radial stretch, square-exponential term, linear coefficient
+        self.Q = Q # radial stretch, square-exponential term, exponent coefficient
+
+    def __call__(self, r):
+        return super().__call__(r) + self.P * (np.exp(self.Q * r * r) - 1)
+
+    def fprime(self, r):
+        """ du/dr = V + SDe^(Dr) + 2 PQr e^(Qr^2) """
+        return super().fprime(r) + 2 * self.P * self.Q * r * np.exp(self.Q * r * r)
+
+    def __str__(self):
+        return f"<{self.__class__.__name__} {self.V=} {self.S=} {self.D=} {self.P=} {self.Q=}>"
+
+    def as_dict(self):
+        return super().as_dict() | dict(
+            P=float(self.P),
+            Q=float(self.Q),
+        )
+
+
+class SaneExponentialTransformer(LinearTransformer):
+    """ Sanitized linear + exponential radial correction, u = Vr + k_1 * (e^(r/r_1) - 1) """
+
+    def __init__(self, V: float = 1, p1: float = 0, r1: float = 0):
+        super().__init__(V)
+        assert abs(r1) > 0.1, "Exponent scale r1 must be > 0.1"
+        self.p1 = p1  # radial stretch, exponential term, linear coefficient
+        self.r1 = r1    # radial stretch, exponential term, exponent coefficient
+
+    def __call__(self, r):
+        return super().__call__(r) + self.p1 * (np.exp(r / self.r1) - 1)
+
+    def fprime(self, r):
+        """ du/dr = V + S / r_1 * e^(r / r_1) """
+        return super().fprime(r) + self.p1 / self.r1 * np.exp(r / self.r1)
+
+    def as_dict(self):
+        return super().as_dict() | dict(
+            p1=float(self.p1),
+            r1=float(self.r1),
+        )
+
+
+class SaneBiexponentialTransformer(SaneExponentialTransformer):
+    def __init__(self, V: float = 0,
+                 p1: float = 0, r1: float = np.inf,
+                 p2: float = 0, r2: float = np.inf):
+        super().__init__(V, p1, r1)
+        assert abs(r2) > 0.1, "Exponent scale r2 must be > 0.1 mm"
+        self.p2 = p2  # radial stretch, square-exponential term, linear coefficient
+        self.r2 = r2  # radial stretch, square-exponential term, exponent coefficient
+
+    def __call__(self, r):
+        return super().__call__(r) + self.p2 * (np.exp((r / self.r2)**2) - 1)
+
+    def fprime(self, r):
+        """ du/dr = V + SDe^(Dr) + 2 PQr e^(Qr^2) """
+        return super().fprime(r) + 2 * self.p2 / self.r2**2 * r * np.exp((r / self.r2)**2)
+
+    def __str__(self):
+        return f"<{self.__class__.__name__} {self.V=} {self.p1=} {self.r1=} {self.p2=} {self.r2=}>"
+
+    def as_dict(self):
+        return super().as_dict() | dict(
+            p2=float(self.p2),
+            r2=float(self.r2),
+        )
+
+

demeteor-0.1.0/demeteor/projections/zenith.py

@@ -0,0 +1,68 @@
+import math
+import numpy as np
+from numpy.typing import NDArray
+
+from typing import Any
+
+from .base import Projection
+
+
+class ZenithShifter(Projection):
+    """
+    ZenithShifter is a spherical -> spherical projection that shifts the zenith to a different
+    position at true zenith distance `epsilon` and rotated such that true zenith is at 180°.
+    """
+
+    name = 'zenith-shifter'
+
+    def __init__(self, epsilon: float = 0, E: float = 0):
+        super().__init__()
+        self.epsilon = epsilon
+        self.E = E
+
+    def __call__(self, u, b):
+        """
+        Parameters
+        ----------
+        u : Union[float, ArrayLike]    radial distance from origin in camera coordinates
+        b : Union[float, ArrayLike]    azimuth in camera coordinates
+
+        Returns
+        -------
+        tuple[Union[float, ArrayLike], Union[float, ArrayLike]]
+        z : Union[float, ArrayLike]    zenith distance in sky coordinates
+        a : Union[float, ArrayLike]    azimuth in sky coordinates
+        """
+        if abs(self.epsilon) < 1e-14:  # for tiny epsilon there is no displacement
+            z = u  # and we are able to calculate the coordinates immediately
+            a = self.E + b
+        else:
+            cosz = np.cos(u) * np.cos(self.epsilon) - np.sin(u) * np.sin(self.epsilon) * np.cos(b)
+            sna = np.sin(b) * np.sin(u)
+            cna = (np.cos(u) - np.cos(self.epsilon) * cosz) / np.sin(self.epsilon)
+            z = np.arccos(cosz)
+            a = self.E + np.arctan2(sna, cna)
+
+        return z, np.mod(a, math.tau)  # wrap around to [0, 2pi)
+
+    def invert(self, z: NDArray, a: NDArray) -> tuple[NDArray, NDArray]:
+        if abs(self.epsilon) < 1e-14:
+            u = z
+            b = a - self.E
+        else:
+            cosu = np.cos(z) * np.cos(self.epsilon) + np.sin(z) * np.sin(self.epsilon) * np.cos(a - self.E)
+            sna = np.sin(a - self.E) * np.sin(z)
+            cna = -(np.cos(z) - np.cos(self.epsilon) * cosu) / np.sin(self.epsilon)
+            u = np.arccos(cosu)
+            b = np.arctan2(sna, cna)
+
+        return u, np.mod(b, math.tau)  # wrap around to [0, 2pi)
+
+    def __str__(self) -> str:
+        return f"<{self.__class__.__name__} {self.epsilon=} {self.E=}>"
+
+    def as_dict(self) -> dict[str, float]:
+        return dict(
+            epsilon=float(self.epsilon),
+            E=float(self.E),
+        )

demeteor-0.1.0/demeteor/trajectory/__init__.py

@@ -0,0 +1 @@
+from .ray import RayMinimizer

demeteor-0.1.0/demeteor/trajectory/ray.py

@@ -0,0 +1,39 @@
+import numpy as np
+import scipy as sp
+
+
+class RayMinimizer:
+    """
+    Class that evaluates the distance of a point from a set of lines, and finds the point
+    from which squared distance to all the lines is smallest.
+
+    Has two constructors: __init__, which expectes two ndarrays of same shape, points and vectors defining the line,
+    and a static `from_points` that expects two arrays of points.
+    """
+    def __init__(self, points: np.ndarray, vectors: np.ndarray, *, normalize: bool = False):
+        assert points.shape == vectors.shape, "Points and vectors must have the same shape"
+
+        self.points = points
+        self.vectors = vectors
+
+        if normalize:
+            self.vectors /= np.linalg.norm(self.vectors)
+
+        assert np.min(np.abs(np.linalg.norm(self.vectors)) != 0), "All vectors must be non-zero!"
+
+    @staticmethod
+    def from_points(points: np.ndarray, points2: np.ndarray):
+        return RayMinimizer(points, points2 - points, normalize=False)
+
+    def sum_distance(self, point: np.array) -> float:
+        p = point - self.points
+        dist = np.linalg.norm(np.cross(p, self.vectors), axis=1, ord=2) / np.linalg.norm(self.vectors, axis=1, ord=2)
+        return np.sum(dist)
+
+    def sum_quad_distance(self, point: np.ndarray) -> float:
+        p = point - self.points
+        dist = np.linalg.norm(np.cross(p, self.vectors), axis=1, ord=2) / np.linalg.norm(self.vectors, axis=1, ord=2)
+        return np.sum(np.square(dist))
+
+    def nearest(self) -> np.ndarray:
+        return sp.optimize.minimize(self.sum_quad_distance, np.array([0, 0, 0]).T, method="L-BFGS-B").x

demeteor-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "demeteor"
+version = "0.1.0"
+description = "A collection of utility functions for all-sky and spectral meteor cameras"
+authors = ["Martin Odokienko <martin.balaz@fmph.uniba.sk>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+numpy = "*"
+scipy = "*"
+pyyaml = "*"
+dotmap = "*"
+pandas = "*"
+astropy = "*"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.2.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"