c4dynamics 2.3.4__tar.gz → 2.3.6__tar.gz

{c4dynamics-2.3.4 → c4dynamics-2.3.6}/PKG-INFO

@@ -1,11 +1,22 @@
 Metadata-Version: 2.4
 Name: c4dynamics
-Version: 2.3.4
+Version: 2.3.6
 Summary: Python framework for state-space modeling and algorithm development
-Author: c4dynamics
 Author-email: Ziv Meri <zivmeri@gmail.com>
 License-Expression: MIT
-Requires-Python: >=3.8,<3.13
+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: 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: matplotlib>=3.9.2
@@ -13,45 +24,17 @@ Requires-Dist: numpy>=1.26.0
 Requires-Dist: pooch>=1.8.0
 Requires-Dist: scipy>=1.13.0
 Provides-Extra: vision
-Requires-Dist: matplotlib>=3.9.2; extra == "vision"
-Requires-Dist: numpy>=1.26.0; extra == "vision"
-Requires-Dist: pooch>=1.8.0; extra == "vision"
-Requires-Dist: scipy>=1.13.0; 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: matplotlib>=3.9.2; extra == "dev"
-Requires-Dist: numpy>=1.26.0; extra == "dev"
-Requires-Dist: pooch>=1.8.0; extra == "dev"
-Requires-Dist: scipy>=1.13.0; extra == "dev"
-Requires-Dist: imageio>=2.37.0; extra == "dev"
-Requires-Dist: natsort>=8.3.1; extra == "dev"
-Requires-Dist: opencv-python>=4.11.0.86; 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-book-theme>=1.1.4; extra == "dev"
 Requires-Dist: sphinx_design>=0.6.1; extra == "dev"
-Provides-Extra: keywords
-Requires-Dist: python; extra == "keywords"
-Requires-Dist: state-space; extra == "keywords"
-Requires-Dist: dynamics; extra == "keywords"
-Requires-Dist: physics; extra == "keywords"
-Requires-Dist: algorithms; extra == "keywords"
-Requires-Dist: control; extra == "keywords"
-Requires-Dist: navigation; extra == "keywords"
-Requires-Dist: guidance; extra == "keywords"
-Requires-Dist: slam; extra == "keywords"
-Requires-Dist: vslam; extra == "keywords"
-Requires-Dist: computer-vision; extra == "keywords"
-Requires-Dist: image-processing; extra == "keywords"
-Requires-Dist: signal-processing; extra == "keywords"
-Provides-Extra: dynamic
-Requires-Dist: classifiers; extra == "dynamic"
-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">
@@ -62,9 +45,7 @@ Dynamic: requires-python
 
 
 <div align="center">
-  <strong>📄 Published in the Journal of Open Source Software (JOSS)</strong><br>
-  <em>A peer-reviewed open-source framework for state-space modeling and algorithm development</em>
-  <br>
+  <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>

{c4dynamics-2.3.4 → c4dynamics-2.3.6}/README.md

@@ -7,9 +7,7 @@
 
 
 <div align="center">
-  <strong>📄 Published in the Journal of Open Source Software (JOSS)</strong><br>
-  <em>A peer-reviewed open-source framework for state-space modeling and algorithm development</em>
-  <br>
+  <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>

c4dynamics-2.3.6/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.6"  # update also in pyproject.toml 
+
+
+#
+# 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])

c4dynamics-2.3.6/c4dynamics/datasets/__init__.py

@@ -0,0 +1,109 @@
+"""
+
+Usage of Datasets
+=================
+
+C4dynamics dataset functions can be simply called as follows:
+:code:`c4dynamics.datasets.module(file)`,
+where ``module`` and ``file`` define the dataset.
+The available modules and files are detailed on the corresponding pages.
+This downloads the dataset file over the network once, saves it to the cache,
+and returns the path to the file.
+
+
+
+
+Dataset retrieval and storage
+=============================
+
+The YOLOv3 weights file can be found at the official YOLO
+site: `Joseph Redmon <https://pjreddie.com/darknet/yolo/>`_.
+Oher dataset files are available in the
+C4dynamics GitHub repository under
+`datasets <https://github.com/C4dynamics/C4dynamics/blob/main/datasets/>`_
+
+
+C4dynamics.datasets uses
+`Pooch <https://www.fatiando.org/pooch/latest/>`_,
+a Python package designed to simplify fetching data files.
+`Pooch` retrieves the necessary dataset files
+from these repositories when the dataset function is called.
+
+
+A registry file of all datasets provides a mapping of filenames
+to their SHA256 hashes and repository URLs
+Pooch uses this registry to manage and verify downloads when the function is called.
+After downloading the dataset once, the files are saved
+in the system cache directory under ``'c4data'``.
+
+
+Dataset cache locations may vary on different platforms.
+
+For Windows::
+
+    'C:\\Users\\<user>\\AppData\\Local\\c4data'
+
+For macOS::
+
+    '~/Library/Caches/c4data'
+
+For Linux and other Unix-like platforms::
+
+    '~/.cache/c4data'  # or the value of the XDG_CACHE_HOME env var, if defined
+
+
+In environments with constrained network connectivity for various security
+reasons or on systems without continuous internet connections,
+one may manually
+load the cache of the datasets by placing the contents of the dataset repo in
+the above mentioned cache directory to avoid fetching dataset errors without
+the internet connectivity.
+
+"""
+
+import sys
+
+# sys.path.append(".")
+
+# from c4dynamics.datasets._manager import (
+#     sha256,
+#     image,
+#     video,
+#     nn_model,
+#     d3_model,
+#     download_all,
+#     clear_cache,
+# )
+from c4dynamics.datasets._manager import sha256 as sha256   # noqa: F401
+from c4dynamics.datasets._manager import image as image   # noqa: F401
+from c4dynamics.datasets._manager import video as video   # noqa: F401
+from c4dynamics.datasets._manager import nn_model as nn_model   # noqa: F401
+from c4dynamics.datasets._manager import d3_model as d3_model   # noqa: F401
+from c4dynamics.datasets._manager import download_all as download_all   # noqa: F401
+from c4dynamics.datasets._manager import clear_cache as clear_cache   # noqa: F401
+
+if __name__ == "__main__":
+
+    # import doctest, contextlib
+    # from c4dynamics import IgnoreOutputChecker, cprint
+
+    # # Register the custom OutputChecker
+    # doctest.OutputChecker = IgnoreOutputChecker
+
+    # tofile = False
+    # optionflags = doctest.FAIL_FAST
+
+    # 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)
+    # else:
+    #   result = doctest.testmod(optionflags = optionflags)
+
+    # if result.failed == 0:
+    #   cprint(os.path.basename(__file__) + ": all tests passed!", 'g')
+    # else:
+    #   print(f"{result.failed}")
+    from c4dynamics import rundoctests
+
+    rundoctests(sys.modules[__name__])