{"id":50721250,"url":"https://github.com/aidenlab/pc2bs","last_synced_at":"2026-06-10T00:01:46.782Z","repository":{"id":352885946,"uuid":"1213603206","full_name":"aidenlab/pc2bs","owner":"aidenlab","description":"Point-cloud Spacewalk .sw to ball-and-stick (CLI, one-way)","archived":false,"fork":false,"pushed_at":"2026-04-21T14:12:26.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T16:23:38.748Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aidenlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T15:01:15.000Z","updated_at":"2026-04-21T14:12:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aidenlab/pc2bs","commit_stats":null,"previous_names":["aidenlab/pc2bs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/aidenlab/pc2bs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fpc2bs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fpc2bs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fpc2bs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fpc2bs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aidenlab","download_url":"https://codeload.github.com/aidenlab/pc2bs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fpc2bs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34130642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T00:01:45.598Z","updated_at":"2026-06-10T00:01:46.769Z","avatar_url":"https://github.com/aidenlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pc2bs\n\n**pc2bs** (point cloud → ball and stick) is a small command-line tool that converts a **point-cloud** Spacewalk `.sw` file into a **ball-and-stick** `.sw` file. The conversion is **one-way** only: it does not turn ball-and-stick files back into point clouds.\n\nThe tool reads and writes [HDF5](https://www.hdfgroup.org/solutions/hdf5/) using [h5py](https://www.h5py.org/). Output files are written as **plain, non-indexed** HDF5 so they load reliably in the [Spacewalk](https://aidenlab.github.io/spacewalk/) web app.\n\n---\n\n## Installation\n\nYou need **Python 3.10 or newer** and a **copy of this repository** on your machine (`git clone` or download a ZIP).\n\n### Option A — You already have a Python environment\n\nIf you already use a Conda env, a `venv`, or a system/user `pip` setup, activate it and install from the repository root:\n\n```bash\ncd /path/to/pc2bs\npython3 -m pip install -e .\n```\n\nThe `-e` (editable) flag means `git pull` picks up source changes immediately — you do not need to reinstall after every update. The only time you need to re-run the install command is when the project's **required libraries** change (for example, a newer minimum version of `h5py` or `numpy`). When that happens, run the same command again:\n\n```bash\npython3 -m pip install -e .\n```\n\n**A note on shared environments.** If your active environment already holds other tools (for example `streamlit`, `numba`, or a Jupyter stack), installing pc2bs into it may pull in newer versions of `numpy` or other shared libraries and trigger pip warnings about **dependency conflicts** with those other tools. pc2bs itself will still work, but the other tools may break. If you hit this, use **Option B** below to install pc2bs into its own dedicated environment. Avoid `pip install --force-reinstall` in a shared environment — it aggressively upgrades transitive libraries and is the most common cause of these conflicts.\n\n### Option B — You do not have a Python environment (use Conda)\n\nIf Python environments are new to you, install [Miniconda](https://docs.conda.io/en/latest/miniconda.html), then create and activate an environment for this tool:\n\n```bash\nconda create -n pc2bs python=3.11\nconda activate pc2bs\ncd /path/to/pc2bs\npython3 -m pip install -e .\n```\n\nRun `conda activate pc2bs` whenever you want to use the tool.\n\n### Verify\n\n```bash\npc2bs --version\n```\n\n---\n\n## Use the tool\n\n### Basic usage\n\n```bash\npc2bs INPUT.sw OUTPUT.sw\n```\n\n- **INPUT.sw** must be a **point-cloud** `.sw` (Spacewalk `multi_point` layout: spatial traces with four values per sample—region index and x, y, z—or equivalent layout recognized by the reader).\n- **OUTPUT.sw** is created (or overwritten) as a **ball-and-stick** `.sw` (`single_point`: one x, y, z per genomic region per trace).\n\nIf you pass a file that is **already** ball-and-stick, the tool exits with an error and does not overwrite your output with a misleading conversion.\n\n### Quiet mode (shell scripts and loops)\n\n```bash\npc2bs -q INPUT.sw OUTPUT.sw\n```\n\n### Standard input and output\n\nYou may use `-` for the input and/or output. The whole HDF5 file is buffered to a temporary file internally (HDF5 needs random access), which is the usual pattern for binary CLI tools.\n\n```bash\npc2bs - OUTPUT.sw \u003c INPUT.sw\npc2bs INPUT.sw - \u003e OUTPUT.sw\n```\n\n### Open the result in Spacewalk\n\nPass `--open` to hand the converted file off to the [Spacewalk](https://aidenlab.org/spacewalk/) web app in your default browser:\n\n```bash\npc2bs --open INPUT.sw OUTPUT.sw\n```\n\npc2bs writes `OUTPUT.sw`, starts a short-lived local web server, and opens a launcher page that uses Spacewalk's `postMessage` protocol (`spacewalk-ready` / `spacewalk-load`) to transfer the file in-memory — no upload and no drag-and-drop. If your browser blocks the pop-up, the launcher page shows a one-click button to continue.\n\nOverride the Spacewalk URL (for a self-hosted build, for example) with `--spacewalk-url`:\n\n```bash\npc2bs --open --spacewalk-url http://localhost:5173/ INPUT.sw OUTPUT.sw\n```\n\n`--open` is incompatible with `OUTPUT = -` (the browser needs a real file to hand off).\n\n---\n\n## Updating\n\nWith your environment activated, pull the latest source and refresh metadata:\n\n```bash\ncd /path/to/pc2bs\ngit pull\npython3 -m pip install -e .\n```\n\nPlain `pip install -e .` leaves already-satisfied libraries alone, so it is safe to run in a shared environment. Avoid `--force-reinstall` unless you are in a dedicated environment — it can upgrade shared libraries (e.g. `numpy`) and break other tools installed alongside pc2bs.\n\n---\n\n## Uninstall\n\nWith your environment activated:\n\n```bash\npython3 -m pip uninstall pc2bs\n```\n\n---\n\n## Troubleshooting\n\n### `pc2bs: command not found`\n\nActivate the environment you installed into (`conda activate pc2bs`, or `source ~/.venvs/pc2bs/bin/activate`), or call the executable by full path (for example `~/.venvs/pc2bs/bin/pc2bs`).\n\n### Errors about HDF5 or missing modules\n\nWith your environment activated, reinstall so dependencies are applied:\n\n```bash\ncd /path/to/pc2bs\npython3 -m pip install -e .\n```\n\nIf that does not resolve the problem and you are using a **dedicated** pc2bs environment (Option B, or a venv used only for pc2bs), you can do a clean refresh with `python3 -m pip install --force-reinstall -e .`. Do not use `--force-reinstall` in a shared environment — it can upgrade `numpy` and other libraries in ways that break other tools installed alongside pc2bs.\n\n### `pip` warns about dependency conflicts during install\n\nIf the install log ends with lines like `ERROR: pip's dependency resolver … this behaviour is the source of the following dependency conflicts` naming packages such as `streamlit`, `numba`, `protobuf`, or `numpy`, pc2bs itself is installed — but the environment you installed into has **other tools** whose pinned versions disagree with what pip just pulled in. Run `pc2bs --version` to confirm pc2bs works. The cleanest fix is to reinstall pc2bs into a dedicated environment (Option B), so its dependencies cannot clobber the other tools.\n\n### Spacewalk still will not open the output file\n\n- Confirm the **input** was really a point-cloud `.sw` (not already ball-and-stick).\n- Try opening the output in an HDF5 viewer (for example [myHDF5](https://myhdf5.hdfgroup.org/)) to confirm the file is valid HDF5.\n- If the problem persists, compare against a known-good ball-and-stick `.sw` from the same project or documentation.\n\n---\n\n## Development (optional)\n\nFrom the repository root:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\npytest\n```\n\nSee [docs/development-notes.md](docs/development-notes.md) for versioning and release notes.\n\n---\n\n## Format reference\n\nSpacewalk documents the `.sw` layout here:\n\n- https://aidenlab.github.io/spacewalk/file-format/specification  \n- https://aidenlab.github.io/spacewalk/file-format/data-structure  \n\nThis tool intentionally does **not** read or write optional datasets such as `live_contact_map_vertices`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidenlab%2Fpc2bs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidenlab%2Fpc2bs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidenlab%2Fpc2bs/lists"}