reflex-ohif-viewer 0.1.0__tar.gz

reflex_ohif_viewer-0.1.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[semantic versioning](https://semver.org/).
+
+## [0.1.0] — 2026-09-17
+
+First release.
+
+### Added
+
+- **`ohif_viewer`** — embeds a self-hosted OHIF Viewer v3 build in an iframe,
+  with every viewer and study-list query parameter exposed as a prop:
+  studies and priors, series filters, initial series and instance, hanging
+  protocol and stage, token, `configUrl`, customization, theme, debug and the
+  `multimonitor` / `screenNumber` pair.
+  Events: `on_viewer_load`, `on_url_change`, `on_viewer_message`.
+- **`build_ohif_url`** — the same URL builder as a plain function, so links can
+  be computed, logged and unit-tested server-side. The Python and JavaScript
+  implementations are pinned to each other by a parity test that runs the
+  JavaScript one under Node.
+- **`dicom_viewer`** — a native Cornerstone3D 5.10.6 viewport: stack, volume
+  (MPR) and 3D volume rendering; 37 tools; window/level, colormap, inversion and
+  cine driven from props; a four-corner DICOM overlay; and a DICOMweb loader
+  that builds `wadors:` imageIds and caches series metadata. Events report the
+  viewer's readiness, slice, window/level, annotations and errors back to Reflex
+  state.
+- **Imperative API** — `set_tool`, `jump_to_slice`, `scroll`, `set_window`,
+  `set_window_preset`, `set_colormap`, `set_zoom`, `rotate`, `flip`,
+  `reset_camera`, `reset_properties`, `play_cine`, `stop_cine`,
+  `clear_measurements`, `remove_measurement` and the general `viewer_call`.
+- **`DicomWebClient`** — QIDO-RS study, series and instance search plus WADO-RS
+  metadata, so a study browser can be ordinary Reflex state.
+- **`OhifAppConfig` / `DicomWebDataSource`** — build OHIF's `window.config` as
+  JavaScript (for `APP_CONFIG` / `app-config.js`), as JSON (for `?configUrl=`)
+  or as a plain mapping, plus `docker_run_command` for a ready-to-run container.
+- **`CornerstonePlugin`** — configures Vite for Cornerstone: keeps the
+  Cornerstone packages out of dependency pre-bundling, forces the CommonJS
+  leaves through it, declares a browser `events` implementation, treats `.wasm`
+  as an asset, emits ES-module workers, and copies the codec `.wasm` files into
+  `public/cs-wasm/`.
+- **Constants** — grouped tool lists, window presets, colormaps, volume-
+  rendering presets, OHIF modes and hanging protocol ids, and four public demo
+  studies whose series UIDs were verified against the live server.
+- **A five-page demo app** — overview, native viewport with a live measurement
+  table, MPR, the OHIF iframe with a URL builder, and a configuration generator.
+
+### Project
+
+- **Continuous integration** — `ci.yml` runs ruff, checks that the generated
+  `.pyi` stubs still match the component source, runs the suite on Python 3.10
+  to 3.13 with Node present so the URL-builder parity test does not skip, and
+  builds the distribution, installs the wheel into a clean environment and
+  imports it to prove the frontend assets are really packaged.
+- **Security validation** — `security.yml` runs Bandit over the published
+  package, `pip-audit` over the installed dependency tree, Gitleaks over the
+  full history, and a dependency review on every pull request; `codeql.yml`
+  analyses both the Python and the JavaScript halves. The two scheduled runs
+  catch advisories published against code that has not changed.
+- **Release automation** — `release.yml` is triggered by a `vX.Y.Z` tag. It
+  refuses to run unless the tag, `pyproject.toml` and this changelog agree,
+  re-runs the checks against the tagged commit, then publishes to PyPI through
+  Trusted Publishing (OpenID Connect — the repository holds no PyPI token) with
+  build attestations, and opens a GitHub Release carrying that version's
+  changelog section.
+- **Packaging** — the licence is declared as a PEP 639 SPDX expression rather
+  than the deprecated classifier, and `MANIFEST.in` puts the changelog, the
+  security policy and the contributing guide into the sdist.
+
+### Security notes
+
+- `viewer_call` validates its `method` argument as a JavaScript identifier. The
+  viewport id and the arguments are JSON-encoded on their way into the generated
+  script, but a method name is a property access and cannot be, so it was the
+  one place a caller could have spliced script into the page.
+
+### Notes on the upstream projects
+
+Checked against the OHIF 3.13.8 source and the published npm tarballs rather
+than the documentation:
+
+- `@ohif/app` on npm is a prebuilt static site. Its `main` points at
+  `dist/index.umd.js`, a file the tarball does not contain, so
+  `import App from '@ohif/app'` has never worked. There is no web component
+  either.
+- OHIF defines no postMessage protocol. `ohif_viewer` therefore builds a URL and
+  nothing more; `on_viewer_message` exists for deployments that add their own
+  OHIF extension.
+- The `:latest` Docker tag and the `latest` npm dist-tag both lag the real
+  stable release — pin `ohif/app:v3.13.8`.
+- `@cornerstonejs/streaming-image-volume-loader` was merged into
+  `@cornerstonejs/core` in 2.x and is not installed.
+- No existing React wrapper for Cornerstone3D was usable:
+  `@cornerstonejs/react` and `react-cornerstone3d` do not exist on npm,
+  `react-cornerstone-viewport` targets the abandoned legacy cornerstone, and
+  `@ohif/ui-next` contains no viewport code.
+
+[0.1.0]: https://github.com/ecrespo/reflex-ohif-viewer/releases/tag/v0.1.0

reflex_ohif_viewer-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,138 @@
+# Contributing
+
+## Getting set up
+
+```bash
+git clone git@github.com:ecrespo/reflex-ohif-viewer.git
+cd reflex-ohif-viewer
+uv venv && source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+Node is optional but recommended: one test runs the JavaScript URL builder under
+Node to check it against the Python one, and skips itself when Node is missing.
+
+## The checks CI runs
+
+Run these before opening a pull request; they are exactly what
+`.github/workflows/ci.yml` and `security.yml` run.
+
+```bash
+ruff check .                              # lint
+ruff format --check .                     # formatting
+pytest -q                                 # tests
+bandit -c pyproject.toml -r custom_components   # Python SAST
+pip-audit                                 # dependency advisories
+python -m build && twine check dist/*     # the artifacts PyPI will get
+```
+
+## Branching and releases
+
+- `main` is the released branch and is protected: no direct pushes, no force
+  pushes, no deletion, and every one of the CI, security and CodeQL checks has
+  to be green before a pull request can merge. A pull request is required but an
+  approving review is not, so a solo maintainer is not locked out; the branch
+  also has to be up to date with `main` before it merges.
+- `develop` is the integration branch. Open your pull request against it.
+- A release is a pull request from `develop` to `main`, then a `vX.Y.Z` tag on
+  `main`. The tag is what triggers `.github/workflows/release.yml`, which builds
+  the artifacts, publishes them to PyPI through Trusted Publishing and opens a
+  GitHub Release.
+
+Every release needs a new version number in `pyproject.toml` — PyPI refuses to
+replace a version that already exists — and a matching `CHANGELOG.md` section.
+The release workflow refuses to run if the tag and `pyproject.toml` disagree.
+
+## Publishing
+
+Nothing in this repository holds a PyPI credential. The release workflow
+authenticates to PyPI over OpenID Connect through
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/), so the
+`pypi` job mints a short-lived token for one upload and there is nothing to
+rotate or leak.
+
+That needs one entry on PyPI, created once by the project owner at
+<https://pypi.org/manage/account/publishing/> (for the very first release, use
+the *pending publisher* form — the project does not exist on PyPI yet):
+
+| Field | Value |
+|---|---|
+| PyPI Project Name | `reflex-ohif-viewer` |
+| Owner | `ecrespo` |
+| Repository name | `reflex-ohif-viewer` |
+| Workflow name | `release.yml` |
+| Environment name | `pypi` |
+
+The `pypi` environment also has to exist in this repository, under
+*Settings → Environments*. It is restricted to a `v*.*.*` tag deployment branch
+policy, so nothing but a version tag can reach it — a run from a branch cannot
+publish even if the workflow were changed to try. Add a required reviewer to the
+environment if you want a human to approve every upload; the workflow will wait
+on it.
+
+To cut a release:
+
+```bash
+# On develop: bump the version and write the changelog section.
+$EDITOR pyproject.toml CHANGELOG.md
+git commit -am "chore: release 0.2.0"
+# Open and merge the pull request into main, then:
+git checkout main && git pull
+git tag -a v0.2.0 -m "v0.2.0"
+git push origin v0.2.0
+```
+
+The tag is the trigger. The workflow re-runs the lint and tests against the
+tagged commit, builds the sdist and wheel, publishes them to PyPI with build
+attestations, and opens a GitHub Release whose notes are that version's
+changelog section.
+
+### Gallery listing
+
+The [Reflex component gallery](https://reflex.dev/docs/custom-components/) is a
+separate registry from PyPI, and registering is manual and done once:
+
+```bash
+reflex login
+reflex component share
+```
+
+It asks for the published package name (`reflex-ohif-viewer`) and, optionally, a
+preview image and a demo URL. Publish to PyPI first — `share` does not check
+that the package exists.
+
+## Working on the component
+
+The two Python component classes have generated `.pyi` stubs next to them,
+marked `DO NOT EDIT`. After adding or changing a prop, regenerate them:
+
+```bash
+python -c "from reflex.utils.pyi_generator import PyiGenerator; \
+PyiGenerator().scan_all(['custom_components/reflex_ohif_viewer'])"
+```
+
+CI checks that the committed stubs match the source, so a forgotten regeneration
+fails the build rather than shipping stale autocomplete.
+
+If you touch `rxOhifUrl.js` or `build_ohif_url`, keep them in step —
+`tests/test_url_builder_parity.py` runs both and compares the result.
+
+## Trying it out
+
+```bash
+cd ohif_viewer_demo
+reflex run
+```
+
+The demo defaults to the public OHIF DICOMweb server. The `/ohif` page needs a
+running OHIF build:
+
+```bash
+docker run -d --name ohif -p 3001:80 ohif/app:v3.13.8
+```
+
+## Scope
+
+This package wraps OHIF and Cornerstone3D; it does not fork them. Bugs in the
+rendering itself belong upstream. What belongs here is the Reflex surface: props,
+events, the URL and config builders, the DICOMweb client and the Vite plugin.

reflex_ohif_viewer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernesto Crespo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reflex_ohif_viewer-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+# The wheel takes its extra files from [tool.setuptools.package-data]; the sdist
+# needs them named here as well, along with the documentation a source release
+# should carry.
+include README.md
+include CHANGELOG.md
+include LICENSE
+include SECURITY.md
+include CONTRIBUTING.md
+recursive-include custom_components/reflex_ohif_viewer *.js *.jsx *.pyi
+include custom_components/reflex_ohif_viewer/py.typed
+recursive-exclude custom_components *.egg-info
+prune ohif_viewer_demo/.web
+prune ohif_viewer_demo/.states