cine-handler 0.1.1__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. cine_handler-0.2.0/.cargo/config.toml +7 -0
  2. cine_handler-0.2.0/.gitattributes +14 -0
  3. cine_handler-0.2.0/.githooks/pre-applypatch +3 -0
  4. cine_handler-0.2.0/.githooks/pre-commit +17 -0
  5. cine_handler-0.2.0/.githooks/pre-merge-commit +3 -0
  6. cine_handler-0.2.0/.github/workflows/publish-python-package.yml +151 -0
  7. cine_handler-0.2.0/CHANGELOG.md +34 -0
  8. cine_handler-0.2.0/Cargo.lock +7 -0
  9. cine_handler-0.2.0/Cargo.toml +8 -0
  10. cine_handler-0.2.0/LICENSE +21 -0
  11. cine_handler-0.2.0/MANIFEST.in +29 -0
  12. cine_handler-0.2.0/Matlab/API.md +140 -0
  13. cine_handler-0.2.0/Matlab/Cine.m +679 -0
  14. cine_handler-0.2.0/Matlab/CineWriter.m +75 -0
  15. cine_handler-0.2.0/Matlab/README.md +188 -0
  16. cine_handler-0.2.0/Matlab/build_cine_backend.m +47 -0
  17. cine_handler-0.2.0/Matlab/build_mex_unpack10bit_cached.m +4 -0
  18. cine_handler-0.2.0/Matlab/check_commit.m +23 -0
  19. cine_handler-0.2.0/Matlab/examples/README.md +40 -0
  20. cine_handler-0.2.0/Matlab/examples/basic_usage.m +59 -0
  21. cine_handler-0.2.0/Matlab/examples/color_processing.m +31 -0
  22. cine_handler-0.2.0/Matlab/examples/images_and_video.m +38 -0
  23. cine_handler-0.2.0/Matlab/examples/processing_and_trim.m +33 -0
  24. cine_handler-0.2.0/Matlab/examples/streaming_write.m +37 -0
  25. cine_handler-0.2.0/Matlab/install_cine_backend.m +56 -0
  26. cine_handler-0.2.0/Matlab/private/cine_backend.m +23 -0
  27. cine_handler-0.2.0/Matlab/private/cine_copy_binary.m +40 -0
  28. cine_handler-0.2.0/Matlab/private/cine_demosaic_bilinear.m +12 -0
  29. cine_handler-0.2.0/Matlab/private/cine_mex.c +323 -0
  30. cine_handler-0.2.0/Matlab/private/cine_prebuilt_info.m +120 -0
  31. cine_handler-0.2.0/Matlab/private/cine_replace_dead_pixels.m +14 -0
  32. cine_handler-0.2.0/Matlab/test_backend_reinstall.m +90 -0
  33. cine_handler-0.2.0/Matlab/test_prebuilt_backend.m +72 -0
  34. cine_handler-0.2.0/Matlab/test_rust_backend.m +153 -0
  35. cine_handler-0.2.0/Matlab/write_cine.m +52 -0
  36. cine_handler-0.2.0/PKG-INFO +153 -0
  37. cine_handler-0.2.0/PYPI.md +109 -0
  38. cine_handler-0.2.0/README.md +150 -0
  39. cine_handler-0.2.0/binaries/README.md +83 -0
  40. cine_handler-0.2.0/binaries/aarch64-apple-darwin/build-info.json +24 -0
  41. cine_handler-0.2.0/binaries/aarch64-apple-darwin/cine-tool +0 -0
  42. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_arm64.dylib → cine_handler-0.2.0/binaries/aarch64-apple-darwin/cine_mex.mexmaca64 +0 -0
  43. cine_handler-0.2.0/binaries/aarch64-apple-darwin/libcine_core.dylib +0 -0
  44. cine_handler-0.2.0/binaries/x86_64-pc-windows-msvc/build-info.json +23 -0
  45. cine_handler-0.2.0/binaries/x86_64-pc-windows-msvc/cine-tool.exe +0 -0
  46. cine_handler-0.2.0/binaries/x86_64-pc-windows-msvc/cine_core.dll +0 -0
  47. cine_handler-0.2.0/binaries/x86_64-pc-windows-msvc/cine_mex.mexw64 +0 -0
  48. cine_handler-0.2.0/binaries/x86_64-unknown-linux-gnu/build-info.json +45 -0
  49. cine_handler-0.2.0/binaries/x86_64-unknown-linux-gnu/cine-tool +0 -0
  50. cine_handler-0.2.0/binaries/x86_64-unknown-linux-gnu/cine_mex.mexa64 +0 -0
  51. cine_handler-0.2.0/binaries/x86_64-unknown-linux-gnu/libcine_core.so +0 -0
  52. cine_handler-0.2.0/docs/BUILDING.md +304 -0
  53. cine_handler-0.2.0/docs/DEVELOPMENT.md +125 -0
  54. cine_handler-0.2.0/docs/RELEASING.md +115 -0
  55. cine_handler-0.2.0/docs/VALIDATION.md +349 -0
  56. cine_handler-0.2.0/miss_hit.cfg +18 -0
  57. {cine_handler-0.1.1 → cine_handler-0.2.0}/pyproject.toml +23 -3
  58. cine_handler-0.2.0/python/API.md +288 -0
  59. cine_handler-0.2.0/python/README.md +100 -0
  60. cine_handler-0.2.0/python/examples/README.md +27 -0
  61. cine_handler-0.2.0/python/examples/basic_usage.py +59 -0
  62. cine_handler-0.2.0/python/examples/convert_media.py +72 -0
  63. cine_handler-0.2.0/python/examples/performance_test.py +71 -0
  64. cine_handler-0.2.0/python/examples/process_arrays.py +49 -0
  65. cine_handler-0.2.0/python/examples/trim_and_background.py +49 -0
  66. cine_handler-0.2.0/python/examples/write_recordings.py +87 -0
  67. cine_handler-0.2.0/python/src/cine_handler.egg-info/SOURCES.txt +113 -0
  68. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/src/cine_reader/__init__.py +5 -0
  69. cine_handler-0.2.0/python/src/cine_reader/_binary.py +308 -0
  70. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/src/cine_reader/_lookup.py +4 -0
  71. cine_handler-0.2.0/python/src/cine_reader/_native.py +269 -0
  72. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/src/cine_reader/cine.py +171 -159
  73. cine_handler-0.2.0/python/src/cine_reader/frame_decode.py +57 -0
  74. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/src/cine_reader/headers.py +65 -19
  75. cine_handler-0.2.0/python/src/cine_reader/image_ops.py +112 -0
  76. cine_handler-0.2.0/python/src/cine_reader/stats.py +94 -0
  77. cine_handler-0.2.0/python/src/cine_reader/unpack.py +51 -0
  78. cine_handler-0.2.0/python/src/cine_reader/writer.py +424 -0
  79. cine_handler-0.2.0/python/tests/data/corpus_reference.json +240 -0
  80. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/tests/test_cine_processing.py +11 -0
  81. cine_handler-0.2.0/python/tests/test_external_corpus.py +33 -0
  82. cine_handler-0.2.0/python/tests/test_ffmpeg_interop.py +80 -0
  83. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/tests/test_frame_decode.py +2 -7
  84. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/tests/test_stats.py +17 -5
  85. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/tests/test_unpack.py +1 -6
  86. cine_handler-0.2.0/python/tests/test_video_python.py +148 -0
  87. cine_handler-0.2.0/python/tests/test_writer.py +200 -0
  88. cine_handler-0.2.0/rust/cine-core/Cargo.toml +12 -0
  89. cine_handler-0.2.0/rust/cine-core/README.md +67 -0
  90. cine_handler-0.2.0/rust/cine-core/include/cine_core.h +74 -0
  91. cine_handler-0.2.0/rust/cine-core/src/bin/cine-tool.rs +81 -0
  92. cine_handler-0.2.0/rust/cine-core/src/ffi.rs +460 -0
  93. cine_handler-0.2.0/rust/cine-core/src/lib.rs +37 -0
  94. cine_handler-0.2.0/rust/cine-core/src/lookup.rs +61 -0
  95. cine_handler-0.2.0/rust/cine-core/src/processing.rs +489 -0
  96. cine_handler-0.2.0/rust/cine-core/src/reader.rs +624 -0
  97. cine_handler-0.2.0/rust/cine-core/src/writer.rs +720 -0
  98. cine_handler-0.2.0/rust/cine-core/tests/reader.rs +170 -0
  99. cine_handler-0.2.0/rust/cine-core/tests/writer.rs +331 -0
  100. cine_handler-0.2.0/sample_data/README.md +10 -0
  101. cine_handler-0.2.0/scripts/build_native.py +71 -0
  102. cine_handler-0.2.0/scripts/check_commit.py +296 -0
  103. cine_handler-0.2.0/scripts/collect_binaries.py +148 -0
  104. cine_handler-0.2.0/scripts/format_code.py +28 -0
  105. cine_handler-0.2.0/scripts/install_hooks.py +72 -0
  106. cine_handler-0.2.0/scripts/release.py +468 -0
  107. cine_handler-0.2.0/scripts/release_install_check.py +121 -0
  108. cine_handler-0.2.0/scripts/tests/test_commit_workflow.py +303 -0
  109. cine_handler-0.2.0/scripts/tests/test_prebuilt_install.py +283 -0
  110. cine_handler-0.2.0/scripts/tests/test_release.py +248 -0
  111. cine_handler-0.2.0/setup.py +121 -0
  112. cine_handler-0.1.1/MANIFEST.in +0 -19
  113. cine_handler-0.1.1/PKG-INFO +0 -358
  114. cine_handler-0.1.1/PYPI.md +0 -329
  115. cine_handler-0.1.1/README.md +0 -140
  116. cine_handler-0.1.1/python/API.md +0 -105
  117. cine_handler-0.1.1/python/README.md +0 -208
  118. cine_handler-0.1.1/python/examples/basic_usage.py +0 -40
  119. cine_handler-0.1.1/python/examples/performance_test.py +0 -72
  120. cine_handler-0.1.1/python/examples/trim_and_background.py +0 -24
  121. cine_handler-0.1.1/python/src/cine_handler.egg-info/SOURCES.txt +0 -29
  122. cine_handler-0.1.1/python/src/cine_reader/frame_decode.py +0 -91
  123. cine_handler-0.1.1/python/src/cine_reader/image_ops.py +0 -285
  124. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_elf64.so +0 -0
  125. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_win32.dll +0 -0
  126. cine_handler-0.1.1/python/src/cine_reader/libs/unpack_data_win64.dll +0 -0
  127. cine_handler-0.1.1/python/src/cine_reader/stats.py +0 -161
  128. cine_handler-0.1.1/python/src/cine_reader/unpack.py +0 -139
  129. {cine_handler-0.1.1 → cine_handler-0.2.0}/pytest.ini +0 -0
  130. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/src/cine_reader/py.typed +0 -0
  131. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/tests/test_cine_smoke.py +0 -0
  132. {cine_handler-0.1.1 → cine_handler-0.2.0}/python/tests/test_image_ops.py +0 -0
  133. {cine_handler-0.1.1 → cine_handler-0.2.0}/setup.cfg +0 -0
@@ -0,0 +1,7 @@
1
+ # Python users should not need a separate Microsoft C runtime installation.
2
+ # Rust allocates and releases its own buffers through the C ABI.
3
+ [target.x86_64-pc-windows-msvc]
4
+ rustflags = ["-C", "target-feature=+crt-static"]
5
+
6
+ [target.aarch64-pc-windows-msvc]
7
+ rustflags = ["-C", "target-feature=+crt-static"]
@@ -0,0 +1,14 @@
1
+ .githooks/* text eol=lf
2
+ LICENSE text eol=lf
3
+ *.py text eol=lf
4
+ *.rs text eol=lf
5
+ *.m text eol=lf
6
+ *.toml text eol=lf
7
+ miss_hit.cfg text eol=lf
8
+ binaries/**/build-info.json text eol=lf
9
+ binaries/**/cine-tool binary
10
+ binaries/**/*.exe binary
11
+ binaries/**/*.dll binary
12
+ binaries/**/*.dylib binary
13
+ binaries/**/*.so binary
14
+ binaries/**/*.mex* binary
@@ -0,0 +1,3 @@
1
+ #!/bin/sh
2
+ set -eu
3
+ exec "$(git rev-parse --show-toplevel)/.githooks/pre-commit"
@@ -0,0 +1,17 @@
1
+ #!/bin/sh
2
+ set -eu
3
+ unset CINE_CHECK_SNAPSHOT
4
+ root=$(git rev-parse --show-toplevel)
5
+ cd "$root"
6
+ python=$(git config --local --get cine.python || true)
7
+ if [ -z "$python" ]; then
8
+ if [ -x "$root/.venv/bin/python" ]; then
9
+ python="$root/.venv/bin/python"
10
+ elif [ -f "$root/.venv/Scripts/python.exe" ]; then
11
+ python="$root/.venv/Scripts/python.exe"
12
+ else
13
+ echo 'Commit blocked: run scripts/install_hooks.py using the project virtual environment.' >&2
14
+ exit 1
15
+ fi
16
+ fi
17
+ exec "$python" "$root/scripts/check_commit.py"
@@ -0,0 +1,3 @@
1
+ #!/bin/sh
2
+ set -eu
3
+ exec "$(git rev-parse --show-toplevel)/.githooks/pre-commit"
@@ -0,0 +1,151 @@
1
+ name: Build and publish Python package
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ release:
6
+ types: [published]
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ build:
13
+ name: Package and test ${{ matrix.target }}
14
+ runs-on: ${{ matrix.os }}
15
+ strategy:
16
+ fail-fast: false
17
+ matrix:
18
+ include:
19
+ - os: macos-15
20
+ architecture: arm64
21
+ target: aarch64-apple-darwin
22
+ sdist: "0"
23
+ - os: windows-2022
24
+ architecture: x64
25
+ target: x86_64-pc-windows-msvc
26
+ sdist: "0"
27
+ - os: ubuntu-24.04
28
+ architecture: x64
29
+ target: x86_64-unknown-linux-gnu
30
+ sdist: "1"
31
+ defaults:
32
+ run:
33
+ shell: bash
34
+ env:
35
+ CINE_RELEASE_OUTPUT: dist/release
36
+ CINE_RELEASE_REPORTS: dist/release-checks
37
+ CINE_RELEASE_SDIST: ${{ matrix.sdist }}
38
+ CINE_RELEASE_TAG: ${{ github.event.release.tag_name }}
39
+ EXPECTED_TARGET: ${{ matrix.target }}
40
+ steps:
41
+ - uses: actions/checkout@v6
42
+ with:
43
+ persist-credentials: false
44
+ - uses: actions/setup-python@v6
45
+ with:
46
+ python-version: "3.13"
47
+ architecture: ${{ matrix.architecture }}
48
+ - name: Install Python packaging tools
49
+ run: |
50
+ python -m pip install --only-binary=:all: "build>=1.2" "twine>=5" "setuptools>=77.0.3" wheel pytest
51
+ - name: Install Linux wheel audit tools
52
+ if: runner.os == 'Linux'
53
+ run: |
54
+ python -m pip install --only-binary=:all: "auditwheel==6.8.2" "patchelf>=0.14.5"
55
+ - name: Verify runner architecture and collected binaries
56
+ run: |
57
+ python - <<'PY'
58
+ import os, sys
59
+ sys.path.insert(0, "scripts")
60
+ import release
61
+ actual = release.binary_module(release.ROOT).host_target()
62
+ assert actual == os.environ["EXPECTED_TARGET"], actual
63
+ release.validate_tag(release.ROOT, os.environ.get("CINE_RELEASE_TAG"))
64
+ release.validate_collection(release.ROOT)
65
+ PY
66
+ - name: Test release validators
67
+ run: python -m pytest scripts/tests/test_release.py -q
68
+ - name: Package existing binaries and audit distributions
69
+ run: python scripts/release.py
70
+ - name: Test Python-only installation and runtime
71
+ run: python scripts/release_install_check.py
72
+ - name: Upload validation logs
73
+ if: always()
74
+ uses: actions/upload-artifact@v7
75
+ with:
76
+ name: install-checks-${{ matrix.target }}
77
+ path: dist/release-checks/
78
+ if-no-files-found: ignore
79
+ - name: Upload verified distributions
80
+ uses: actions/upload-artifact@v7
81
+ with:
82
+ name: distributions-${{ matrix.target }}
83
+ path: dist/release/*
84
+ if-no-files-found: error
85
+
86
+ assemble:
87
+ name: Verify complete release set
88
+ needs: build
89
+ runs-on: ubuntu-24.04
90
+ steps:
91
+ - uses: actions/checkout@v6
92
+ with:
93
+ persist-credentials: false
94
+ - uses: actions/setup-python@v6
95
+ with:
96
+ python-version: "3.13"
97
+ - uses: actions/download-artifact@v8
98
+ with:
99
+ pattern: distributions-*
100
+ merge-multiple: true
101
+ path: dist/release/
102
+ - name: Validate exactly three wheels and one source archive
103
+ env:
104
+ CINE_RELEASE_MODE: validate
105
+ CINE_RELEASE_TAG: ${{ github.event.release.tag_name }}
106
+ run: |
107
+ python -m pip install --only-binary=:all: packaging "twine>=5"
108
+ python scripts/release.py
109
+ python -m twine check dist/release/*
110
+ - uses: actions/upload-artifact@v7
111
+ with:
112
+ name: python-package-distributions
113
+ path: dist/release/*
114
+ if-no-files-found: error
115
+
116
+ publish:
117
+ name: Publish to PyPI
118
+ if: ${{ github.event_name == 'release' && !github.event.release.prerelease }}
119
+ needs: assemble
120
+ runs-on: ubuntu-latest
121
+ environment:
122
+ name: pypi
123
+ url: https://pypi.org/project/cine-handler/
124
+ permissions:
125
+ id-token: write
126
+ steps:
127
+ - uses: actions/download-artifact@v8
128
+ with:
129
+ name: python-package-distributions
130
+ path: dist/
131
+ - name: Publish verified distributions using Trusted Publishing
132
+ uses: pypa/gh-action-pypi-publish@release/v1
133
+
134
+ attach-release-assets:
135
+ name: Attach release assets
136
+ if: ${{ github.event_name == 'release' && !github.event.release.prerelease }}
137
+ needs: [assemble, publish]
138
+ runs-on: ubuntu-latest
139
+ permissions:
140
+ contents: write
141
+ steps:
142
+ - uses: actions/download-artifact@v8
143
+ with:
144
+ name: python-package-distributions
145
+ path: dist/
146
+ - name: Upload verified distributions to the GitHub release
147
+ env:
148
+ GH_TOKEN: ${{ github.token }}
149
+ GH_REPO: ${{ github.repository }}
150
+ RELEASE_TAG: ${{ github.event.release.tag_name }}
151
+ run: gh release upload "$RELEASE_TAG" dist/*
@@ -0,0 +1,34 @@
1
+ # Changelog
2
+
3
+ ## 0.2.0
4
+
5
+ - Move CINE I/O, memory management, decoding, writing and pixel processing into a
6
+ dependency-free Rust backend shared by Python, MATLAB and the standalone tool.
7
+ - Preserve the existing Python and MATLAB reading APIs while opening lazily and
8
+ decoding frames on demand. Add canonical top-down/RGB reading as an opt-in.
9
+ - Write normal and packed10 CINE files from arrays, image sequences and videos,
10
+ including incremental output and disk-spooled unknown-length input.
11
+ - Add PyAV video conversion through Python packages, without separate FFmpeg
12
+ programs for ordinary users.
13
+ - Include verified native libraries for Apple Silicon macOS, Windows x64 and
14
+ glibc Linux x64. Python wheels, source archives and GitHub checkouts use prebuilt
15
+ libraries without Rust or C toolchains.
16
+ - Add a MATLAB-only installer for the collected MEX gateways and shared libraries.
17
+ - Verify native MATLAB installation on all three collected platforms. Prevent
18
+ Linux reinstallation/rebuild crashes from overwriting a retained shared library,
19
+ and require a restart before replacing a changed backend that remains loaded.
20
+ - Expand Python/MATLAB API documentation and runnable feature examples, add the
21
+ MIT license file, and remove obsolete C implementation/build distributions.
22
+ - Require staged formatting, linting, compilation and tests before local commits
23
+ after hook installation. Prepare a three-platform wheel publishing workflow.
24
+
25
+ Packed10 is quantized; RGB packed10 input is sampled into a Bayer mosaic. Direct
26
+ PCC acceptance remains unverified. Intel macOS, ARM64 Windows/Linux and musl Linux
27
+ need separate native builds. These limitations are detailed in the build and
28
+ validation guides.
29
+
30
+ ## 0.1.1
31
+
32
+ Previous published Python reader package, before the shared Rust backend and
33
+ CINE writing features. Historical release artifacts remain available through Git
34
+ history and the package/release services rather than as binaries under `release/`.
@@ -0,0 +1,7 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 3
4
+
5
+ [[package]]
6
+ name = "cine-core"
7
+ version = "0.2.0"
@@ -0,0 +1,8 @@
1
+ [workspace]
2
+ members = ["rust/cine-core"]
3
+ resolver = "2"
4
+
5
+ [profile.release]
6
+ lto = "thin"
7
+ codegen-units = 1
8
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rees Verleur
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,29 @@
1
+ include LICENSE README.md PYPI.md CHANGELOG.md
2
+ include pyproject.toml setup.py pytest.ini miss_hit.cfg
3
+ include .gitattributes
4
+ include Cargo.toml Cargo.lock .cargo/config.toml
5
+ graft python/src
6
+ graft python/examples
7
+ graft python/tests
8
+ include python/README.md python/API.md
9
+ graft rust/cine-core/src
10
+ graft rust/cine-core/include
11
+ graft rust/cine-core/tests
12
+ include rust/cine-core/Cargo.toml rust/cine-core/README.md
13
+ graft Matlab
14
+ graft scripts
15
+ graft .githooks
16
+ graft .github
17
+ include docs/BUILDING.md docs/DEVELOPMENT.md docs/VALIDATION.md docs/RELEASING.md
18
+ include sample_data/README.md
19
+ graft binaries
20
+
21
+ # Native artifacts live only in binaries/. Wheels select one matching library.
22
+ prune python/src/cine_reader.egg-info
23
+ prune python/src/cine_handler.egg-info
24
+ prune python/src/cine_reader/libs
25
+ prune Matlab/private/lib
26
+ prune python/examples/output
27
+ prune Matlab/examples/output
28
+ recursive-exclude Matlab *.mex*
29
+ global-exclude __pycache__ *.py[cod] .DS_Store
@@ -0,0 +1,140 @@
1
+ # MATLAB API
2
+
3
+ Install the prebuilt backend once per checkout/update with
4
+ `addpath('<repo>/Matlab'); install_cine_backend`. Ordinary use needs MATLAB only;
5
+ developer builds are explicitly requested with `build_cine_backend`. See
6
+ [installation, compatibility and examples](README.md).
7
+
8
+ ## Reader
9
+
10
+ The reader's existing call signatures remain available:
11
+
12
+ - `Cine(filename, 'RemoveDeadPixels', false, 'Debayer', false, 'DeadValue', [], 'BayerPattern', 'auto')`
13
+ - `OpenCineFile(filename)`, `CloseFile()`, `LoadFrame(frame_no)`, `NextFrame(increment)`
14
+ - `ReplaceDeadPixels(dead_value)`, `DebayerFrame(bayer_pattern)`, `GetFrameRGB(frame_no, bayer_pattern)`
15
+ - `AverageFrames(start_frame, end_frame, replace, chunk_size)`
16
+ - `ModeFrames(start_frame, end_frame, replace, 'method', 'auto', 'q_bg', .8, 'k_sigma', 2.5, 'min_keep', 3, 'max_keep', 96, 'stack_limit', 128)`
17
+ - `LoadFramesBatch(start_frame, count)`
18
+ - `SaveFramesToNewFile(output_filename, start_frame, end_frame)`
19
+
20
+ Frame ranges are inclusive and use the file's global frame numbers, which may
21
+ be negative. `LoadFramesBatch` explicitly allocates the requested batch;
22
+ ordinary reads retain only the current frame. `chunk_size` is validated and
23
+ retained for compatibility; the Rust mean accumulator streams frames directly.
24
+ `NextFrame` defaults to increment 1. Out-of-range reads raise an error.
25
+
26
+ `PixelArray` and `RawPixelArray` use the historical storage row orientation:
27
+ positive `ImageHeader.biHeight` means bottom-up. Interpolated color frames have
28
+ BGR channels; `GetFrameRGB` changes these to RGB or demosaics a raw Bayer image,
29
+ retaining row orientation. `DebayerFrame` changes `PixelArray` to RGB while
30
+ `RawPixelArray` keeps the decoded input. For top-down presentation or passing a
31
+ read frame to `CineWriter`, flip the rows when `biHeight > 0`, and convert BGR
32
+ to RGB if needed. Packed10 decoding returns linearized uint16 values, not raw
33
+ 10-bit packed codes.
34
+
35
+ `LoadFramesBatch` returns H-by-W-by-count for mono/raw Bayer and
36
+ H-by-W-by-3-by-count for color (MATLAB can omit trailing singleton dimensions).
37
+ Returned arrays survive subsequent loads and closing the reader.
38
+
39
+ Constructor processing options are case-insensitive name/value pairs:
40
+
41
+ | Option | Default | Meaning |
42
+ | --- | --- | --- |
43
+ | `RemoveDeadPixels` | false | Repair matching marker values on each read |
44
+ | `DeadValue` | [] | Default marker 4095; specify the actual marker for your data |
45
+ | `Debayer` | false | Demosaic raw CFA data on each read |
46
+ | `BayerPattern` | `'auto'` | Infer CFA from metadata, or use RGGB/BGGR/GRBG/GBRG |
47
+
48
+ One-off repair and demosaicing mutate the current `PixelArray`. Raw CFA repair
49
+ uses same-color neighbors. Demosaicing is bilinear and applies no white balance,
50
+ gamma correction or tone mapping. `RedPixels`, `GreenPixels` and `BluePixels`
51
+ contain sensor samples with NaN at other color sites, rather than interpolated
52
+ full-color planes.
53
+
54
+ `AverageFrames` returns the integer-rounded mean in the current frame type.
55
+ `ModeFrames` returns a uint16 robust bright-background estimate for mono/raw
56
+ Bayer frames. `method='auto'` selects MAD for short ranges (`stack_limit`) and
57
+ top-k for longer ranges; MAD stores the selected frame stack, while top-k bounds
58
+ retained samples using `max_keep`. `q_bg` sets the bright-background quantile,
59
+ `k_sigma` controls MAD rejection, and `min_keep` controls the minimum samples.
60
+ This is not an exact histogram mode. The `replace` argument enables dead-pixel
61
+ repair for the statistic without changing the constructor configuration.
62
+
63
+ `SaveFramesToNewFile` copies the selected encoded frames without quantizing or
64
+ re-encoding them, retaining global frame numbers and slicing timestamp tags.
65
+ The destination must not exist.
66
+
67
+ `FileHeader`, `ImageHeader`, `CameraSetup`, `CurrentFrame`, `PixelArray`,
68
+ `RawPixelArray`, `ImageLocations`, `AnnotationSize`, `AnnotationData`,
69
+ `Annotation`, `ImageSize`, `RedPixels`, `GreenPixels` and `BluePixels` retain
70
+ their public names. Initial image state and the offsets vector are lazy.
71
+ `CameraSetup` materializes its legacy `SetupData` bytes, including tagged blocks,
72
+ on first access. Internal frame reading uses the cached fixed setup metadata.
73
+ Rust preserves/subsets tagged blocks as appropriate when trimming.
74
+ Explicit `CloseFile` materializes deferred initial image and metadata state so
75
+ these public properties remain available after closing. Deleting or reopening
76
+ an object releases the discarded state without materializing it.
77
+
78
+ Set `KeepAnnotations=true` before reading a frame to retain its annotation
79
+ bytes. `UseMemMap`, `AssumeConstAnn` and `Debug` remain compatibility properties;
80
+ the Rust backend controls I/O and validates bounds independently of them.
81
+
82
+ ## Streaming writer
83
+
84
+ `CineWriter(filename, width, height, name, value, ...)` accepts:
85
+
86
+ | Option | Default | Meaning |
87
+ |---|---|---|
88
+ | `Channels` | 1 | 1 mono/Bayer or 3 RGB |
89
+ | `BitDepth` | 8 | uint8 at 8, uint16 at 9–16 |
90
+ | `Packed10` | false | Phantom packed10 gamma encoding, linear12 input |
91
+ | `FrameCount` | 0 | Known count; 0 means unknown-length stream |
92
+ | `FirstFrame` | 0 | First global frame number |
93
+ | `CFA` | 0 | Raw Bayer CFA identifier; 0 for mono/RGB |
94
+ | `FrameRate` | 30 | Positive frames per second |
95
+
96
+ Frames have top-down rows, with size H-by-W for mono/Bayer or H-by-W-by-3 for
97
+ RGB. Normal formats preserve samples exactly within the selected bit depth.
98
+ For Bayer data use `Channels=1` and the matching `CFA`: 3=GBRG, 4=RGGB, 5=GRBG,
99
+ 6=BGGR (legacy identifiers 1=GBRG and 2=BGGR are also accepted).
100
+
101
+ With `Packed10=true`, the output depth is 12. uint8 input is scaled to linear12;
102
+ RGB input is sampled into the chosen Bayer CFA (RGGB by default). This is lossy.
103
+ uint16 packed10 inputs must be in [0,4095]; samples are quantized to the nearest
104
+ entry in the Phantom linearization table. This does not preserve arbitrary
105
+ 16-bit values, and RGB-to-Bayer sampling discards two channels per site.
106
+ `WriteFrame(frame)` appends one frame, `Close()` finalizes and publishes,
107
+ `Abort()` discards unfinished output. `FramesWritten` counts successful writes.
108
+ The destructor aborts unfinished output; explicitly close successful writes.
109
+ An incorrect known `FrameCount` prevents successful finalization. Use
110
+ `FrameCount=0` for unknown lengths: the writer uses a temporary disk spool and
111
+ one final streaming copy, not a full in-memory video. Existing destinations are
112
+ protected. Use `onCleanup(@() delete(writer))` to abort if a loop errors.
113
+
114
+ ## Image and video conversion
115
+
116
+ `write_cine(filename, frames, name, value, ...)` accepts a cell array of arrays
117
+ or image paths, a string array of image paths, or a MATLAB `VideoReader`.
118
+ Options are forwarded to `CineWriter`; dimensions/channels/type are inferred
119
+ from the first frame and VideoReader's frame rate is used by default.
120
+ Supply image paths in the desired temporal order; paths are loaded one at a
121
+ time. Indexed images are converted to RGB. Arbitrary format changes between
122
+ frames are rejected. Video format support is determined by MATLAB's installed
123
+ codecs, and video conversion consumes the `VideoReader` from its current
124
+ position. Variable source timing is represented using the chosen constant
125
+ `FrameRate`; per-frame acquisition timestamps are not recovered from video.
126
+
127
+ ## Installation and validation
128
+
129
+ - `install_cine_backend`: verify and copy the matching collected Rust library
130
+ and MEX gateway; uses the OS-provided SHA256 utility, no compiler tools.
131
+ - `build_cine_backend`: compile the Rust library and C gateway with the local
132
+ developer toolchain. `build_mex_unpack10bit_cached` is its compatibility alias.
133
+ - `test_rust_backend(corpus_directory)`: synthetic reader/writer and media tests;
134
+ optionally test first/middle/last frames of all camera CINEs in a directory.
135
+ - `test_prebuilt_backend`: validate current collected artifacts and exercise
136
+ rejection of stale sources, corrupt/missing binaries and wrong ABI metadata.
137
+
138
+ The collected gateways' tested MATLAB releases and platform requirements are
139
+ listed in [README.md](README.md). MATLAB/CINE examples are under
140
+ [examples/](examples/); none require Image Processing or Statistics Toolbox.