c4dynamics 2.3.2__tar.gz → 2.3.5__tar.gz

{c4dynamics-2.3.2/c4dynamics.egg-info → c4dynamics-2.3.5}/PKG-INFO

@@ -1,35 +1,40 @@
 Metadata-Version: 2.4
 Name: c4dynamics
-Version: 2.3.2
+Version: 2.3.5
 Summary: Python framework for state-space modeling and algorithm development
-Author: c4dynamics
 Author-email: Ziv Meri <zivmeri@gmail.com>
 License-Expression: MIT
-Keywords: python,state-space,dynamics,physics,algorithms,computer vision,navigation,guidance,slam,vslam,image processing,signal processing,control
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
+Project-URL: Homepage, https://github.com/c4dynamics/c4dynamics/discussions
+Project-URL: Documentation, https://c4dynamics.github.io/c4dynamics/
+Project-URL: Source, https://github.com/c4dynamics/c4dynamics
+Project-URL: Issues, https://github.com/c4dynamics/c4dynamics/issues
+Keywords: python,state-space,dynamics,physics,algorithms,control,navigation,guidance,slam,vslam,computer-vision,image-processing,signal-processing
 Classifier: Programming Language :: Python :: 3
-Classifier: Operating System :: Unix
-Classifier: Operating System :: MacOS :: MacOS X
-Classifier: Operating System :: Microsoft :: Windows
-Requires-Python: >=3.8,<3.13
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.13,>=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: imageio>=2.37.0
 Requires-Dist: matplotlib>=3.9.2
-Requires-Dist: natsort>=8.3.1
 Requires-Dist: numpy>=1.26.0
-Requires-Dist: opencv-python>=4.11.0.86
 Requires-Dist: pooch>=1.8.0
 Requires-Dist: scipy>=1.13.0
+Provides-Extra: vision
+Requires-Dist: imageio>=2.37.0; extra == "vision"
+Requires-Dist: natsort>=8.3.1; extra == "vision"
+Requires-Dist: opencv-python>=4.11.0.86; extra == "vision"
 Provides-Extra: dev
+Requires-Dist: c4dynamics[vision]; extra == "dev"
+Requires-Dist: coverage>=7.0.0; extra == "dev"
 Requires-Dist: nbsphinx>=0.9.3; extra == "dev"
-Requires-Dist: Sphinx>=8.1.3; extra == "dev"
+Requires-Dist: sphinx>=8.1.3; extra == "dev"
 Requires-Dist: sphinx-book-theme>=1.1.4; extra == "dev"
 Requires-Dist: sphinx_design>=0.6.1; extra == "dev"
-Dynamic: author
 Dynamic: license-file
-Dynamic: requires-python
 
 <div align="center">
   <img src="https://github.com/C4dynamics/C4dynamics/blob/main/docs/source/_icon/c4dlogotext.svg">
@@ -37,6 +42,25 @@ Dynamic: requires-python
 
 
 
+
+
+<div align="center">
+  <strong> Published in the Journal of Open Source Software (JOSS)</strong><br>
+  <a href="https://doi.org/10.5281/zenodo.17931207">
+    <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.17931207.svg">
+  </a>
+  <br>
+  <a href="https://doi.org/10.21105/joss.08776">
+    <img src="https://joss.theoj.org/papers/10.21105/joss.08776/status.svg">
+  </a>
+</div>
+
+<br>
+
+
+
+
+
 # Tsipor Dynamics
 
 ## Algorithms Engineering and Development
@@ -57,9 +81,24 @@ Tsipor (bird) Dynamics (c4dynamics) is the Python framework for state-space mode
 ![Pepy Total Downloads](https://img.shields.io/pepy/dt/c4dynamics?style=for-the-badge&color=blue%20&link=https%3A%2F%2Fpepy.tech%2Fprojects%2Fc4dynamics%3FtimeRange%3DthreeMonths%26category%3Dversion%26includeCIDownloads%3Dtrue%26granularity%3Ddaily%26viewType%3Dline%26versions%3D2.0.3%252C2.0.1%252C2.0.0)
 
 
+## About c4dynamics
 
+**c4dynamics** is designed to 
+simplify the development of algorithms for dynamic systems, 
+using state space representations. 
+It offers engineers and researchers a systematic approach to model, 
+simulate, and control systems in fields like 
+``robotics, aerospace,`` and ``navigation``.
 
-[Documentation](https://c4dynamics.github.io/c4dynamics/)
+The framework introduces ``state objects,`` which are foundational 
+data structures that encapsulate state vectors and provide 
+the tools for managing data, simulating system behavior, 
+and analyzing results. 
+
+With integrated modules for sensors, 
+detectors, and filters, 
+c4dynamics accelerates algorithm development 
+while maintaining flexibility and scalability.
 
 
 ## Why c4dynamics?
@@ -78,24 +117,15 @@ Tsipor (bird) Dynamics (c4dynamics) is the Python framework for state-space mode
 
 
 
+## Documentation
 
-**c4dynamics** is designed to 
-simplify the development of algorithms for dynamic systems, 
-using state space representations. 
-It offers engineers and researchers a systematic approach to model, 
-simulate, and control systems in fields like 
-``robotics, aerospace,`` and ``navigation``.
-
-The framework introduces ``state objects,`` which are foundational 
-data structures that encapsulate state vectors and provide 
-the tools for managing data, simulating system behavior, 
-and analyzing results. 
-
-With integrated modules for sensors, 
-detectors, and filters, 
-c4dynamics accelerates algorithm development 
-while maintaining flexibility and scalability.
+📘 **Full documentation:**  
+https://c4dynamics.github.io/c4dynamics/
 
+- Installation and setup guides  
+- Core concepts and state-space modeling philosophy  
+- API reference and examples  
+- Tutorials for filtering, sensing, and simulation workflows
 
 
 ## Requirements 
@@ -124,24 +154,25 @@ To run the latest GitHub version, download the repo and install required package
 >>> pip install -r requirements.txt
 ```
 
- 
- 
- 
 
 ## Quickstart
 
 Import c4dynamics:
-```
+```python
 >>> import c4dynamics as c4d
 ```
 
 Define state space object of two variables in the state space (y, vy) with initial conditions (change the state with your variables): 
-```
+```python
 >>> s = c4d.state(y = 1, vy = 0.5)
 ``` 
+Store with time stamp `t = 0`:
+```python 
+>>> s.store(t = 0)
+``` 
 
 Multiply the state vector by a matrix and store:  
-```
+```python
 >>> F = [[1, 1],                      
          [0, 1]]              
 >>> s.X += F @ s.X                     
@@ -149,7 +180,7 @@ Multiply the state vector by a matrix and store:
 ```
 
 Print the state variables, the state vector, and the stored data:  
-```
+```python
 >>> print(s)  
 [ y  vy ]
 >>> s.X 

{c4dynamics-2.3.2 → c4dynamics-2.3.5}/README.md

@@ -4,6 +4,25 @@
 
 
 
+
+
+<div align="center">
+  <strong> Published in the Journal of Open Source Software (JOSS)</strong><br>
+  <a href="https://doi.org/10.5281/zenodo.17931207">
+    <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.17931207.svg">
+  </a>
+  <br>
+  <a href="https://doi.org/10.21105/joss.08776">
+    <img src="https://joss.theoj.org/papers/10.21105/joss.08776/status.svg">
+  </a>
+</div>
+
+<br>
+
+
+
+
+
 # Tsipor Dynamics
 
 ## Algorithms Engineering and Development
@@ -24,9 +43,24 @@ Tsipor (bird) Dynamics (c4dynamics) is the Python framework for state-space mode
 ![Pepy Total Downloads](https://img.shields.io/pepy/dt/c4dynamics?style=for-the-badge&color=blue%20&link=https%3A%2F%2Fpepy.tech%2Fprojects%2Fc4dynamics%3FtimeRange%3DthreeMonths%26category%3Dversion%26includeCIDownloads%3Dtrue%26granularity%3Ddaily%26viewType%3Dline%26versions%3D2.0.3%252C2.0.1%252C2.0.0)
 
 
+## About c4dynamics
 
+**c4dynamics** is designed to 
+simplify the development of algorithms for dynamic systems, 
+using state space representations. 
+It offers engineers and researchers a systematic approach to model, 
+simulate, and control systems in fields like 
+``robotics, aerospace,`` and ``navigation``.
 
-[Documentation](https://c4dynamics.github.io/c4dynamics/)
+The framework introduces ``state objects,`` which are foundational 
+data structures that encapsulate state vectors and provide 
+the tools for managing data, simulating system behavior, 
+and analyzing results. 
+
+With integrated modules for sensors, 
+detectors, and filters, 
+c4dynamics accelerates algorithm development 
+while maintaining flexibility and scalability.
 
 
 ## Why c4dynamics?
@@ -45,24 +79,15 @@ Tsipor (bird) Dynamics (c4dynamics) is the Python framework for state-space mode
 
 
 
+## Documentation
 
-**c4dynamics** is designed to 
-simplify the development of algorithms for dynamic systems, 
-using state space representations. 
-It offers engineers and researchers a systematic approach to model, 
-simulate, and control systems in fields like 
-``robotics, aerospace,`` and ``navigation``.
-
-The framework introduces ``state objects,`` which are foundational 
-data structures that encapsulate state vectors and provide 
-the tools for managing data, simulating system behavior, 
-and analyzing results. 
-
-With integrated modules for sensors, 
-detectors, and filters, 
-c4dynamics accelerates algorithm development 
-while maintaining flexibility and scalability.
+📘 **Full documentation:**  
+https://c4dynamics.github.io/c4dynamics/
 
+- Installation and setup guides  
+- Core concepts and state-space modeling philosophy  
+- API reference and examples  
+- Tutorials for filtering, sensing, and simulation workflows
 
 
 ## Requirements 
@@ -91,24 +116,25 @@ To run the latest GitHub version, download the repo and install required package
 >>> pip install -r requirements.txt
 ```
 
- 
- 
- 
 
 ## Quickstart
 
 Import c4dynamics:
-```
+```python
 >>> import c4dynamics as c4d
 ```
 
 Define state space object of two variables in the state space (y, vy) with initial conditions (change the state with your variables): 
-```
+```python
 >>> s = c4d.state(y = 1, vy = 0.5)
 ``` 
+Store with time stamp `t = 0`:
+```python 
+>>> s.store(t = 0)
+``` 
 
 Multiply the state vector by a matrix and store:  
-```
+```python
 >>> F = [[1, 1],                      
          [0, 1]]              
 >>> s.X += F @ s.X                     
@@ -116,7 +142,7 @@ Multiply the state vector by a matrix and store:
 ```
 
 Print the state variables, the state vector, and the stored data:  
-```
+```python
 >>> print(s)  
 [ y  vy ]
 >>> s.X 

c4dynamics-2.3.5/c4dynamics/__init__.py

@@ -0,0 +1,326 @@
+"""
+
+C4DYNAMICS
+==========
+
+c4dynamics provides
+  1. State objects as fundamental data structure for dynamic systems.
+  2. Internal systems and 3rd party integrated libraries.
+  3. Fast algorithmic operations over objects and systems.
+
+
+How to use the documentation
+----------------------------
+Documentation is currently availble through examples,
+readme pages, and inline comments.
+
+
+Available subpackages
+---------------------
+sensors
+  Models of EO and EM sensors.
+detectors
+  Objects detection models.
+filters
+  Kalman and lowpass filters.
+eqm
+  Runge Kutta solvers for integrating the equations of motion.
+rotmat
+  Rotation matrices and rotational operations.
+"""
+
+import os
+import sys
+import doctest
+import warnings
+import subprocess
+import numpy as np
+
+#
+# body objects
+##
+from . import rotmat as rotmat
+from .states.lib.pixelpoint import pixelpoint as pixelpoint
+from .states.lib.datapoint import datapoint as datapoint
+from .states.lib.datapoint import create as create
+from .states.state import state as state
+
+# rotmat is required to importing rigidbody:
+from .states.lib.rigidbody import rigidbody as rigidbody  # rotmat is required to import rigidbody.
+
+#
+# routines
+##
+from . import eqm as eqm
+
+#
+# utils
+##
+from .utils.const import *  # noqa: F403
+from .utils.math import *  # noqa: F403
+from .utils.gen_gif import gif as gif
+from .utils.cprint import cprint as cprint
+from .utils.plottools import plotdefaults as plotdefaults
+from .utils.plottools import _figdef as _figdef
+from .utils.plottools import _legdef as _legdef
+from .utils import tictoc as tictoc
+from .utils.tictoc import tic as tic
+from .utils.tictoc import toc as toc
+from .utils._struct import struct as struct
+from .utils.idx2keys import idx2keys as idx2keys
+from . import datasets as datasets
+
+#
+# sensors
+##
+from . import sensors as sensors
+from . import filters as filters
+from . import detectors as detectors
+
+#
+# reinforcement learning
+##
+from . import envs as envs  # noqa: F401
+
+#
+# version
+##
+__version__ = "2.3.5"  # update also in pyproject.toml & setup.py
+
+
+#
+# some convinient mirroring
+##
+j = os.path.join
+
+
+"""
+WARNINGS
+"""
+
+
+class c4warn(UserWarning):
+    pass
+
+
+# customize the warning messages:
+YELLOW = "\033[93m"
+RESET = "\033[0m"  # Reset color to default
+
+
+# Override showwarning to globally apply custom formatting
+def show_warning(message, category, filename, lineno, file=None, line=None):
+
+    if issubclass(category, c4warn):
+        # Apply formatting for c4warn warnings
+
+        # FIXME suppressing is absolutely not working.
+        message1 = str(message) + "\n"
+        message2 = "To suppress c4dynamics' warnings, run: import warnings," \
+                   "import c4dynamics as c4d, warnings.simplefilter('ignore', c4d.c4warn)\n"
+
+        print(f"\n{YELLOW}{message1}{RESET}{message2} (File: {filename}, Line: {lineno})")
+    else:
+        # For other warnings, use the default behavior
+        print(f"{category.__name__}: {message} (File: {filename}, Line: {lineno})")
+
+
+warnings.showwarning = show_warning
+
+"""
+TESTING
+"""
+
+
+class IgnoreOutputChecker(doctest.OutputChecker):
+    from typing import Union
+
+    IGNORE_OUTPUT = doctest.register_optionflag("IGNORE_OUTPUT")  # 2048
+    NUMPY_FORMAT = doctest.register_optionflag("NUMPY_FORMAT")  # 4096
+
+    def check_output(self, want, got, optionflags):
+
+        # If the IGNORE_OUTPUT flag is set, always return True
+        if optionflags & self.IGNORE_OUTPUT:
+            return True
+
+        # If NUMPY_FORMAT flag is set, compare NumPy arrays with formatting tolerance
+        if optionflags & self.NUMPY_FORMAT:
+
+            want = self._convert_to_array(want)
+            got = self._convert_to_array(got)
+
+            if want is not None and got is not None:
+
+                abs_tol = 1e-3
+                rel_tol = 1e-3
+
+                if False:
+
+                    # Calculate element-wise absolute and relative differences
+                    # if diff < abs (for small values) OR diff/want < rel (for large values)
+                    np.abs(want - got) < abs_tol
+                    np.abs((want - got) / np.where(want != 0, want, np.inf)) < rel_tol
+
+                return np.allclose(want, got, atol=abs_tol, rtol=rel_tol)
+
+        # Otherwise, fall back to the original behavior
+        return super().check_output(want, got, optionflags)  # type: ignore
+
+    def _convert_to_array(self, text):
+
+        import re
+
+        """Attempt to convert text to a NumPy array for comparison."""
+        try:
+
+            if "," not in text:
+                text = re.sub(r"\s+", ",", text.strip())
+
+            # Remove 'np.type'
+            text = re.sub(r"np\.\w+", "", text)
+            # Remove 'array(' and strip leading/trailing whitespace characters
+            text = re.sub(r"(array\()", "", text).strip()
+            # Remove brackets and parantheses
+            text = re.sub(r"[\[\]\(\)]", "", text)
+            # remove ellipsis
+            text = re.sub(r"\.\.\.", "", text)
+            # Convert to NumPy array
+            return np.fromstring(text, sep=",")
+
+        except ValueError:
+            print(
+                "\n \033[31m DOCSTRING ERROR: Could not convert to an array \033[0m",
+                file=sys.stderr,
+            )
+            return None  # Return None if conversion fails
+
+    # Filter out tests for the animate method by overriding the testmod.
+
+
+def testmod_filtering(module, filter_functions=[], **kwargs):
+
+    tests = []
+
+    for test in doctest.DocTestFinder().find(module):
+        filtfunc = False
+        for func in filter_functions:
+            if func == test.name:
+                filtfunc = True
+                break
+        if filtfunc:
+            continue
+        tests.append(test)
+
+    runner = doctest.DocTestRunner(**kwargs)
+    for test in tests:
+        runner.run(test)
+    return runner.summarize()
+
+
+def rundoctests(module, exclude_functions=[]):
+    import doctest
+    import contextlib
+    import os
+    from c4dynamics import IgnoreOutputChecker  # , cprint
+
+    # from matplotlib import pyplot as plt
+    from pathlib import Path
+
+    tofile = False
+    # pltbe = plt.get_backend()
+    # plt.switch_backend("tkAgg")
+
+    # Register the custom OutputChecker
+    doctest.OutputChecker = IgnoreOutputChecker
+
+    optionflags = doctest.FAIL_FAST
+    np.set_printoptions(legacy="1.25")
+
+    if tofile:
+        with open(os.path.join("tests", "_out", "output.txt"), "w") as f:
+            with contextlib.redirect_stdout(f), contextlib.redirect_stderr(f):
+                # result = doctest.testmod(optionflags = optionflags)
+                result = testmod_filtering(module, exclude_functions, optionflags=optionflags)
+    else:
+        # result = doctest.testmod(optionflags = optionflags)
+        result = testmod_filtering(module, exclude_functions, optionflags=optionflags)
+
+    if result.failed == 0:
+        cprint(Path(module.__file__).parts[-1] + ": all tests passed!", "g")
+    else:
+        print(f"{result.failed}")
+
+    # plt.switch_backend(pltbe)
+
+
+"""
+ROOT FOLDER
+"""
+
+
+# just find the package root folder:
+def c4dir(dir, addpath=""):
+    # dirname and basename are supplamentary:
+    # c:\dropbox\c4dynamics\text.txt
+    # dirname: c:\dropbox\c4dynamics
+    # basename: text.txt
+
+    inc4d = os.path.basename(dir) == "c4dynamics"
+    hasc4d = any(f == "c4dynamics" for f in os.listdir(dir) if os.path.isdir(os.path.join(dir, f)))
+
+    if inc4d and hasc4d:
+        addpath += ""
+        return addpath
+
+    addpath += "..\\"
+    return c4dir(os.path.dirname(dir), addpath)
+
+
+"""
+KEYWORDS
+"""
+#
+# TODO BUG FIXME HACK NOTE XXX
+#
+# TODO IMPROVMEMNT
+#
+# BUG LOGICAL FAILURE PROBABLY COMES WITH XXX
+#     Highlights the presence of a bug or an issue.
+# FIXME NOT SEVERE BUT A BETTER IDEA IS TO DO SO
+#       Indicates that there is a problem or bug that needs to be fixed.
+# HACK I KNOW ITS NOT BEST SOLUTION TREAT IF U HAVE SPARE TIME
+#      Suggests that a workaround or temporary solution has been
+#      implemented and should be revisited.
+# NOTE MORE IMPORTANT THAN A CASUAL COMMENT
+#      Provides additional information or context about the code.
+# XXX TREAT THIS BEFORE OTHERS
+#     Used to highlight something that is problematic, needs attention,
+#     or should be addressed later.
+
+
+# FIXME
+# dependencies: for time limits requirementx.txt currently
+# install all. actually maybe 90% of the users use only numpy
+# and pyplot so it's a good practice to offer another full-req.txt
+# file and add an import check for those not necessary:
+
+
+def ensure_package(package_name):
+    try:
+        __import__(package_name)
+    except ImportError:
+        # Check if the user is in a conda environment
+        in_conda_env = os.environ.get("CONDA_PREFIX") is not None
+        manager = "conda" if in_conda_env else "pip"
+
+        user_input = input(
+            f"{package_name} is required but not installed. "
+            f"Would you like to install it with {manager}? (y/n): "
+        )
+
+        if user_input.lower() == "y":
+            if manager == "conda":
+                subprocess.check_call(["conda", "install", package_name, "-y"])
+            else:
+                subprocess.check_call(["pip", "install", package_name])