Metadata-Version: 2.4
Name: pycadu
Version: 0.1.0
Summary: Satellite-agnostic CCSDS/CADU/VCDU frame handling
Project-URL: Source, https://github.com/mraspaud/pycadu
Project-URL: Issues, https://github.com/mraspaud/pycadu/issues
Author-email: Martin Raspaud <martin.raspaud@smhi.se>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.14
Requires-Dist: numpy>=2.0
Description-Content-Type: text/x-rst

pycadu
======

Satellite-agnostic CCSDS/CADU/VCDU frame handling in Python.

Reads raw downlink files containing CADU (Channel Access Data Unit) blocks,
reassembles VCDU payloads, and yields fixed-length instrument frames delimited
by a caller-supplied sync pattern.  Works with any CCSDS-compliant downlink:
VIIRS, MERSI, MODIS, etc.

Installation
------------

.. code-block:: bash

    pip install pycadu

Quick start
-----------

.. code-block:: python

    from pycadu import iter_vcdu_frames

    MERSI_SYNC = bytes([0xAA, 0x55] * 6)
    MERSI_FRAME_SIZE = 0x38E4F4
    MERSI_VCID = 3

    for frame in iter_vcdu_frames(
        "FY3D_20240101.dat",
        pattern=MERSI_SYNC,
        frame_size=MERSI_FRAME_SIZE,
        vcid=MERSI_VCID,
        stride=1024,          # or 896 / 1072 depending on ground station
    ):
        process(frame)

API
---

``pycadu``
~~~~~~~~~~

- ``iter_vcdu_frames(path, pattern, frame_size, vcid, stride)`` — top-level convenience.

``pycadu.cadu``
~~~~~~~~~~~~~~~

- ``detect_cadu_stride(data)`` — infer stride (896 / 1024 / 1072) from a sample.
- ``extract_cadu_data(block, stride)`` — strip RS parity / annotation bytes.
- ``extract_vcdu_payload(cadu)`` — strip CCSDS primary header.
- ``extract_vcid(block)`` — read the 6-bit virtual channel identifier.
- ``CADU_STRIDE_1072`` — 1072-byte stride (1024-byte CADU + 48 annotation bytes).

``pycadu.sync``
~~~~~~~~~~~~~~~

- ``find_sync_pattern(data, pattern, start)`` — search at all 8 bit offsets.
- ``_build_shifted(data, shift)`` — build a bit-shifted copy of *data*.

``pycadu.reader``
~~~~~~~~~~~~~~~~~

- ``cadu_blocks(path, stride)`` — stream physical blocks from a file.
- ``vcdu_payloads(blocks, stride, target_vcid)`` — filter by VCID, strip headers.
- ``vcdu_frames(payloads, pattern, frame_size)`` — reassemble variable-length
  chunks into fixed-length frames, handling 0-7 bit shifts automatically.
- ``read_frames_batch(path, stride, vcid, pattern, frame_size)`` — memory-mapped
  bulk reader, ~20x faster than the streaming path on large files.

``pycadu.constants``
~~~~~~~~~~~~~~~~~~~~

``CCSDS_SYNC_MARKER``, ``CADU_STRIDE_896``, ``CADU_STRIDE_1024``,
``RS_PARITY_LENGTH``, ``CADU_DATA_LENGTH``, ``CCSDS_HEADER_LENGTH``,
``VCDU_PAYLOAD_LENGTH``.
