plexora 0.0.1__tar.gz

plexora-0.0.1/LICENSE

@@ -0,0 +1,207 @@
+Plexora Academic License 1.0
+SPDX-License-Identifier: LicenseRef-Plexora-Academic-1.0
+
+Copyright (c) 2026 Nirmal Lab. All rights reserved.
+
+Plexora is free to use for academic research, teaching, and other
+noncommercial purposes. Commercial use requires a separate paid license.
+Plugins are welcome: you may build and distribute them freely, and you own
+what you write. What you may not do is publish a modified copy or fork of
+Plexora itself.
+
+For a commercial license, contact Ajit Johnson Nirmal
+<ajitjohnson.n@gmail.com>.
+
+The summary above is for orientation only. The terms below are what govern.
+
+--------------------------------------------------------------------------
+
+1. DEFINITIONS
+
+   "Software" means Plexora, including its source code, object code,
+   documentation, and bundled assets, as made available by the Licensor,
+   excluding Third-Party Components (Section 8).
+
+   "Licensor" means Nirmal Lab.
+
+   "You" means the individual or legal entity exercising rights under this
+   License. If you are acting in the course of your employment or
+   engagement, "You" includes your employer or the entity engaging you.
+
+   "Noncommercial Purpose" means any use that is not a Commercial Use,
+   including academic research, classroom and educational use, personal
+   study, and use by a nonprofit research institute, public research
+   organization, charitable organization, or government body. Use by such
+   an organization is a Noncommercial Purpose regardless of the source of
+   its funding, including funding from a commercial entity, provided the
+   use itself is not a Commercial Use.
+
+   "Commercial Use" means use of the Software that is directed toward
+   commercial advantage or monetary compensation, including without
+   limitation: use by or on behalf of a for-profit entity in its business
+   operations; use to provide services to third parties for a fee; use to
+   develop, test, manufacture, validate, or support a product or service
+   that is sold or licensed for a fee; use in fee-for-service contract
+   research; and incorporating the Software or its output into a commercial
+   product or offering.
+
+   "Plugin" means software that extends the Software solely through the
+   Software's documented extension interfaces -- the `plexora.plugins`
+   entry point group and the public API exposed by the `plexora.api`
+   package -- and that does not include, embed, or require any modification
+   to the Software.
+
+   "Modified Version" means any copy of the Software in which any file has
+   been added, removed, altered, renamed, or replaced, and any work that is
+   a derivative work of the Software under copyright law. A Plugin is not
+   a Modified Version.
+
+2. GRANT FOR NONCOMMERCIAL USE
+
+   Subject to your compliance with this License, the Licensor grants you a
+   worldwide, royalty-free, non-exclusive, non-transferable, non-
+   sublicensable license to:
+
+   (a) install, run, and use the Software for any Noncommercial Purpose;
+
+   (b) reproduce and distribute verbatim, unmodified copies of the
+       Software, provided that each copy retains this License in full and
+       all copyright and attribution notices; and
+
+   (c) make modifications to your own copy of the Software, solely for your
+       own internal Noncommercial use -- for example to fix a bug, resolve
+       a compatibility problem in your environment, or debug an issue --
+       subject to Section 3.
+
+   No fee may be charged for the Software itself under this grant. Recovery
+   of actual media or bandwidth costs for distributing a verbatim copy is
+   permitted.
+
+3. NO DISTRIBUTION OF MODIFIED VERSIONS
+
+   You may not distribute, publish, share, host, sell, sublicense, or
+   otherwise make available to any third party any Modified Version, in
+   source or object form, in whole or in part. This includes publishing a
+   public fork of the Software's repository, distributing patched builds or
+   container images, redistributing the Software under a different name,
+   and making a Modified Version available to third parties as a hosted or
+   network-accessible service.
+
+   Modifications you make under Section 2(c) must remain within your own
+   organization. You are encouraged, but not required, to submit them to
+   the Licensor for possible inclusion upstream.
+
+   Nothing in this Section restricts your distribution of Plugins, which is
+   governed by Section 4.
+
+4. PLUGINS
+
+   You may write, use, distribute, sell, and license Plugins without
+   restriction under this License, and without needing the Licensor's
+   permission.
+
+   You own the Plugins you write and may license them on any terms you
+   choose, including commercial terms. A Plugin is not a Modified Version
+   and is not subject to Section 3 or to the noncommercial limitation in
+   Section 2, whether or not it is distributed together with the Software.
+
+   For the avoidance of doubt: linking to, importing, calling, subclassing,
+   or registering against the Software's documented extension interfaces
+   does not by itself make your Plugin a derivative work of the Software
+   for the purposes of this License.
+
+   Distributing the Software itself alongside your Plugin remains subject
+   to Section 2(b) -- the copy of the Software must be verbatim.
+
+5. COMMERCIAL USE
+
+   This License grants no rights for Commercial Use. Any Commercial Use
+   requires a separate written license from the Licensor. To obtain one,
+   contact Ajit Johnson Nirmal <ajitjohnson.n@gmail.com>.
+
+6. RESERVATION OF RIGHTS; NO TRADEMARK LICENSE
+
+   All rights not expressly granted are reserved by the Licensor. This
+   License does not grant permission to use the trade names, trademarks,
+   service marks, product names, or logos of the Licensor, including the
+   name "Plexora", except as required for reasonable and customary
+   descriptive use in reproducing the notices required by this License.
+
+   This License grants no patent rights.
+
+7. ATTRIBUTION AND NOTICES
+
+   Any copy of the Software you distribute, and any publication or
+   presentation reporting results obtained using the Software, must retain
+   or provide, as applicable, the copyright notice above and a reference to
+   this License. Academic users are asked to cite the Software in
+   accordance with the citation information provided with it.
+
+8. THIRD-PARTY COMPONENTS
+
+   The Software is distributed with components authored by third parties
+   and licensed under their own terms. Those components remain governed
+   exclusively by their own licenses, which are unaffected by this License;
+   in particular, nothing in Section 3 restricts any right you hold in a
+   Third-Party Component under that component's own license. Known
+   Third-Party Components include:
+
+   - plexora/server/utils/smallestenclosingcircle.py -- Copyright (c) 2020
+     Project Nayuki, LGPL-3.0-or-later.
+   - the contents of plexora/client/external/ -- see the notices in that
+     directory.
+   - third-party Python and JavaScript dependencies installed alongside the
+     Software, each under its own license.
+
+   Where a Third-Party Component's license conflicts with a term of this
+   License as applied to that component, that component's license controls
+   for that component.
+
+9. FAIR USE AND MANDATORY RIGHTS
+
+   This License does not limit any right you have under applicable law that
+   cannot be limited by agreement, including fair use, fair dealing, and
+   any statutory right to decompile or modify the Software for
+   interoperability or error correction.
+
+10. TERM AND TERMINATION
+
+   This License applies for as long as you comply with it. If you breach
+   any term, your rights under this License terminate automatically.
+
+   If the breach is your first and you cure it in full, and take
+   reasonable steps to correct its effects, within 30 days of receiving
+   written notice from the Licensor, your rights are reinstated as of the
+   date of cure.
+
+   On termination you must cease all use of the Software and destroy all
+   copies in your possession or control. Sections 3, 6, 8, 11, and 12
+   survive termination. Termination does not affect any license you or
+   anyone else holds in a Plugin.
+
+11. NO WARRANTY
+
+   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, TITLE, AND
+   NONINFRINGEMENT.
+
+   THE SOFTWARE IS A RESEARCH TOOL. IT IS NOT A MEDICAL DEVICE AND IS NOT
+   INTENDED, VALIDATED, OR APPROVED FOR CLINICAL DIAGNOSIS, TREATMENT, OR
+   ANY OTHER USE INVOLVING PATIENT CARE.
+
+12. LIMITATION OF LIABILITY
+
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL THE LICENSOR
+   OR ANY CONTRIBUTOR 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, INCLUDING ANY INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+   CONSEQUENTIAL DAMAGES, OR ANY LOSS OF DATA, PROFITS, OR RESEARCH
+   RESULTS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+13. SEVERABILITY
+
+   If any provision of this License is held unenforceable, that provision
+   shall be enforced to the maximum extent permissible and the remaining
+   provisions shall remain in full force and effect.

plexora-0.0.1/MANIFEST.in

@@ -0,0 +1,16 @@
+recursive-include plexora/client/templates *.html
+recursive-include plexora/client/dist *
+recursive-include plexora/client/src/css *.css
+recursive-include plexora/client/src/img *
+recursive-include plexora/client/src/js *.js
+recursive-include plexora/client/src/shaders *.glsl
+recursive-include plexora/client/external *
+recursive-include plexora/plugins *.html
+# Per plugin rather than a plugins/*/static glob: MANIFEST.in has no such glob,
+# so every bundled plugin's assets need a line of their own here or they are
+# simply absent from an sdist -- which builds and installs fine, then serves a
+# tool with no client.
+recursive-include plexora/plugins/cell_explorer/static *
+recursive-include plexora/plugins/figure_builder/static *
+recursive-include plexora/plugins/gating/static *
+recursive-include plexora/plugins/roi/static *

plexora-0.0.1/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: plexora
+Version: 0.0.1
+Summary: OpenSeadragon-based cellular image viewing and analysis tool.
+License-Expression: LicenseRef-Plexora-Academic-1.0
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anndata>=0.10
+Requires-Dist: Flask>=3.1
+Requires-Dist: h5py>=3.16.0
+Requires-Dist: imagecodecs
+Requires-Dist: itsdangerous>=2.2
+Requires-Dist: Jinja2>=3.1
+Requires-Dist: numpy>=2.0
+Requires-Dist: ome-types>=0.6.3
+Requires-Dist: orjson>=3.11
+Requires-Dist: pandas>=3.0.5
+Requires-Dist: Pillow>=10.4
+Requires-Dist: platformdirs>=4
+Requires-Dist: polars>=1.43
+Requires-Dist: pydantic<2.14,>=2.13
+Requires-Dist: reportlab>=5.0.1
+Requires-Dist: scikit-image
+Requires-Dist: scikit-learn>=1.9
+Requires-Dist: scipy
+Requires-Dist: shapely>=2.1.2
+Requires-Dist: spatialdata>=0.8.0
+Requires-Dist: threadpoolctl>=3.6.0
+Requires-Dist: tifffile>=2026.7.31
+Requires-Dist: waitress
+Requires-Dist: Werkzeug>=3.1
+Requires-Dist: zarr>=3
+Provides-Extra: jupyter
+Requires-Dist: ipython; extra == "jupyter"
+Requires-Dist: jupyter-server-proxy; extra == "jupyter"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-randomly>=4.1.0; extra == "dev"
+Dynamic: license-file
+
+# Plexora
+
+![](./plexora/client/src/img/logo_with_text.svg)
+
+## About
+This is  an [openseadragon](https://openseadragon.github.io/) based **Cellular Image Viewing and Analysis Tool**. 
+It is built with a python [Flask](http://flask.pocoo.org/) backend and a [Node.js](https://nodejs.org/en/) javascript frontend.
+
+## Install (for Users)
+
+```bash
+pip install plexora
+plexora
+```
+
+That is the whole setup. `plexora` starts the server, prints the URL, and opens
+a browser when the environment looks interactive. On the first run it also
+prints where it will keep your projects.
+
+```bash
+plexora my_dataset        # open a project straight away
+plexora --port 9000       # a specific port (8000 is the default; if it is
+                          # busy, Plexora moves to a free one and says so)
+plexora --version
+python -m plexora         # same thing, when the console script is not on PATH
+```
+
+There are four ways to run Plexora, all of which end in the same viewer:
+
+| Where you are | What to run |
+| --- | --- |
+| Your own machine, a terminal | `plexora` |
+| Your own machine, a notebook | `plexora.view("my_dataset")` |
+| A remote machine you can ssh into | `plexora connect user@host` — or `plexora --remote` on the host |
+| A hosted notebook (JupyterHub, Open OnDemand, Colab) | `plexora.view("my_dataset")` — the proxy is detected for you |
+
+**[DEPLOYMENT.md](DEPLOYMENT.md) walks through all of them in detail**, from a
+fresh conda environment to HPC job submission, with the real output of each
+command. The rest of this README is the short version.
+
+### Where your data lives
+
+Plexora keeps projects, figures and settings in one directory, chosen in this
+order:
+
+| Rule | Location |
+| --- | --- |
+| `--data-dir` / `PLEXORA_DATA_PATH` | whatever you pass |
+| a recorded setting | `plexora config set data-dir <path>` |
+| default | `%LOCALAPPDATA%\plexora`, `~/Library/Application Support/plexora`, or `~/.local/share/plexora` |
+
+It never depends on the directory you started from, and never lives inside the
+installed package.
+
+```bash
+plexora where                          # which directory, and which rule chose it
+plexora config set data-dir /scratch/me/plexora
+```
+
+Moving it matters on HPC and on Windows machines with a small system drive:
+derived image pyramids are large, and the default sits on your home or system
+volume. `plexora config set data-dir` records the choice permanently; the
+environment variable overrides it for one run.
+
+### Shared projects
+
+Several people on one workstation or login node can share a directory of common
+datasets while keeping their own work private:
+
+```bash
+export PLEXORA_SHARED_PATH=/srv/plexora/common   # or: plexora config set shared-dirs ...
+plexora
+```
+
+Shared projects appear in Open Project marked *Shared*. They can be opened and
+explored but not edited or deleted, and everything you produce while exploring
+one — gates, ROIs, figures, cached results — is written to **your** data
+directory, not the shared one. A project of your own with the same name takes
+precedence over the shared copy.
+
+Plexora has no user accounts and no authentication. For a multi-user
+deployment, run one process per user behind a reverse proxy that maps the
+authenticated user to their own `--data-dir`, and keep the server bound to
+loopback (the default).
+
+## Running on a remote machine over SSH
+
+Plexora binds to loopback and has no authentication, so the way to reach one
+running on a server is an SSH tunnel rather than an open port. There are two
+ways to get one, and they do the same thing.
+
+**Have Plexora set it up.** Run this on *your own* computer:
+
+```bash
+plexora connect user@server.lab.edu                 # starts, tunnels, opens a browser
+plexora connect user@server.lab.edu my_dataset      # …straight into a project
+```
+
+It stays in the foreground; Ctrl+C closes the tunnel and stops the remote
+server. It uses your system `ssh`, so whatever `~/.ssh/config`, an agent, a
+ProxyJump or a hardware token already do for `ssh user@host` happens here too.
+
+If the remote `plexora` is not on a non-interactive `PATH` — which is common
+with conda — name it explicitly:
+
+```bash
+plexora connect user@server.lab.edu --remote-command "conda run -n imaging plexora"
+```
+
+**Or do it by hand.** On the remote machine:
+
+```bash
+plexora --remote
+```
+
+It prints the exact `ssh -N -L …` command to paste into a terminal on your own
+computer, and the `http://localhost:<port>/` address to open afterwards.
+
+### HPC clusters with compute nodes
+
+On a cluster you usually may not run anything heavy on the login node, so
+Plexora belongs in a job. `--srun` submits one and tunnels to whichever node
+the scheduler grants — the target is the *login* node:
+
+```bash
+plexora connect user@o2.hms.harvard.edu --srun "-p interactive -t 4:00:00 --mem 16G"
+```
+
+Allocation may queue; it says so while it waits. Ctrl+C ends the job.
+
+By hand, the same thing is two steps: start an interactive job
+(`srun --pty -p interactive -t 4:00:00 --mem 16G bash`), then run
+`plexora --remote` inside it. It detects the job, works out which compute node
+it is on and which login node you came through, and prints the two-hop
+`ssh -J` command for it.
+
+Some sites refuse SSH into a compute node. Add `--bind-node` at either end for
+a login-node forward instead — note that this makes the port reachable from
+the cluster's internal network while it runs.
+
+A lab's shared reference data pairs naturally with this: point
+`PLEXORA_SHARED_PATH` (or `plexora config set shared-dirs`) at a read-only
+directory on the cluster filesystem, and `--data-dir` or
+`plexora config set data-dir` at your own scratch space.
+
+## Running as a Docker container
+**Note:** When running on an ARM machine (e.g. M1 Macbook), build the image with `docker build --platform linux/amd64 -t plexora .`
+* Build image: `docker build -t plexora .` 
+* Run image with mounted path: `docker run --rm -dp 8000:8000 -v [source path]:/[target path] plexora`
+
+where
+* `--rm` cleans up the container after it finishes executing
+* `-v` mounts the "present working directory" (containing your data) to be `/data` inside the container. This is necessary in order to import your data via the import page.
+* `-dp` forwards the port 8000
+
+Once the container is running, go to `http://localhost:8000/` in your web browser. 
+To import your imaging files in the import gui type in the mounted `/data/..`
+
+Inside the image, projects are written to `/app/data` (`PLEXORA_DATA_PATH`), so
+mount a volume there to keep them between runs:
+
+```bash
+docker run --rm -dp 8000:8000 -v ~/plexora-data:/app/data -v /my/images:/data plexora
+```
+
+The image also sets `PLEXORA_HOST=0.0.0.0` — published ports would never reach
+it otherwise — and `PLEXORA_DOCKER=1`, which switches the import page to
+container-shaped path hints.
+
+## Clone and Run Codebase (for Developers)
+
+```bash
+git clone https://github.com/nirmallab/plexora.git
+cd plexora
+python -m venv .venv && source .venv/bin/activate   # or conda create -n plexora python=3.13
+pip install -e ".[dev,jupyter]"
+```
+
+Any Python 3.12 or 3.13 environment works — conda, venv, uv, whatever you
+already use. The editable install pulls every runtime dependency plus the test
+and notebook extras; there is no separate environment file to keep in sync.
+
+Then start the server with `python run.py` (or `plexora`) and open
+`http://localhost:8000/`.
+
+## Running in Jupyter notebooks
+
+Install the package into the same environment as Jupyter:
+
+```bash
+pip install "plexora[jupyter]"
+```
+
+Then, in a cell:
+
+```python
+import plexora
+
+plexora.view("my_dataset")
+```
+
+That is the whole thing, in every kind of notebook. Plexora starts a small
+server beside your kernel and shows it in the cell.
+
+`data_dir` is optional everywhere below: leaving it out uses the same directory
+`plexora where` reports, so a notebook and a terminal see the same projects.
+Pass it to work against a different one.
+
+### Hosted notebooks — JupyterHub, Open OnDemand, Colab
+
+The same call. When your kernel is not on the machine with your browser, a
+`127.0.0.1` address would point at your own laptop, so Plexora detects the
+situation and builds the proxied URL your host actually serves it on.
+
+On a JupyterHub or Open OnDemand server, this needs `jupyter-server-proxy`
+installed **in the environment running the Jupyter server** (not necessarily
+the one running your kernel):
+
+```bash
+pip install jupyter-server-proxy
+```
+
+Colab needs nothing extra. Neither does local Jupyter or VS Code Remote, which
+keep the direct localhost address they always used.
+
+Override the detection if you need to:
+
+```python
+plexora.view("my_dataset", proxy=True)     # always proxy
+plexora.view("my_dataset", proxy=False)    # always use 127.0.0.1
+plexora.view("my_dataset", base_url="/user/me/")   # name the prefix yourself
+```
+
+On a hub, `viewer.url` is a path rather than a full address — open it under
+your notebook server's own address, which is where your session is
+authenticated.
+
+Datasets can also be registered directly from notebook-visible files:
+
+```python
+from plexora.jupyter import PlexoraViewer
+
+viewer = PlexoraViewer.from_files(
+    name="my_dataset",
+    image="/path/to/image.ome.tif",
+    segmentation="/path/to/segmentation.ome.tif",
+    features="/path/to/cells.csv",
+    x="X_centroid",
+    y="Y_centroid",
+    id_column="CellID",
+)
+viewer
+```
+
+## Baseline smoke test
+
+Before upgrading dependencies or changing the viewer/server boundary, run the local `orion2` baseline:
+
+```bash
+python -m tests.baseline_orion2
+```
+
+The test checks Flask app import, `/config`, the viewer page, metadata JSON, channel metadata, and one image tile plus one segmentation tile. It skips with a clear message if the local `orion2` datasource or exemplar files are not available.
+
+
+#### (4. Node.js installation and packages)
+  This step is only needed when you plan to edit js code. The codebase already included bundled js files.
+* Install [Node.js](https://nodejs.org/en/), then navigate to `/plexora/client` and run `npm install` to install all packages listed in package.json.
+* Run `npm run start` to package the Javascript, or run `npm run watch` if you plan on editing dependencies
+
+
+## Packaging/Bundling Code as Executable (for Developers)
+Any tagged commit to a branch will trigger a build, where `tag == commit message`. This will appear under releases. Note building may take ~10 min.
+
+Tagging Conventions: All release tags should look like `v{version_number}_{branch_name}`.
+
+## License
+
+Plexora is released under the **Plexora Academic License 1.0** (see [LICENSE](./LICENSE)).
+It is **not** an open source license. In short:
+
+| | |
+|---|---|
+| Academic research, teaching, personal study | ✅ Free |
+| Use by a nonprofit or government research institution | ✅ Free (whatever the funding source) |
+| Redistributing Plexora unmodified, with the license attached | ✅ Allowed |
+| Patching your own copy to fix a bug or a compatibility problem | ✅ Allowed |
+| Publishing a fork, a patched build, or a renamed version | ❌ Not allowed |
+| Commercial use of any kind | ❌ Requires a paid license |
+
+**Plugins are a deliberate exception.** Anything you build against the documented
+extension interfaces — the `plexora.plugins` entry point group and the `plexora.api`
+package — is yours. You may distribute and sell your plugin under whatever license
+you like, and you do not need our permission. Extending Plexora through the plugin
+API is the supported way to change what it does; editing its source is not.
+
+For a commercial license, contact Ajit Johnson Nirmal <ajitjohnson.n@gmail.com>.
+
+Some bundled components carry their own licenses, which are unaffected by the above —
+see section 8 of [LICENSE](./LICENSE).