bump: v0.1.10; change: better token instruction; better README

Author: huangziwei

README.md

@@ -1,16 +1,19 @@
 # flatone
 
-A command-line tool to (1) download one EyeWire II neuron mesh as `.obj`, (2) skeletonize it as `.swc` and (3) flatten it automatically.
+A command-line tool that automatically (1) downloads the mesh of an EyeWire II neuron as `.obj` with [CaveClient/CloudVolume](https://github.com/seung-lab/cloud-volume), (2) skeletonizes it as an `.swc` with [skeliner](https://github.com/berenslab/skeliner) and (3) flattens it with [pywarper](https://github.com/berenslab/pywarper).
+
+## Installation
+
+__NOTE__: `flatone` relies on SuiteSparse, which does **NOT** run on native Windows. Use it on Unix-like enviroment or Windows Subsystem for Linux (WSL 2) instead.
 
-## Installation and Usage
 
 ```bash
 # prerequisites
 ## mac
 brew update
 brew install suite-sparse
 
-## debian/ubuntu/WSL
+## debian/ubuntu/WSL 
 sudo apt-get update
 sudo apt-get install build-essential # if not already installed
 sudo apt-get install libsuitesparse-dev
@@ -27,23 +30,53 @@ pip install -e .
 
 # but it's highly recommended to install it within a venv env
 # here we use uv again but of course you can run python -m venv 
-uv venv .venv --python 3.13
+uv venv .venv --python 3.13 # any versions>=3.10 should work
 source .venv/bin/activate
 uv pip install -e .
 
 # now you can check if it works
 flatone -v 
 ```
 
-Assuming you have a CAVEClient token stored in your environment, you can run the full pipeline in one line:
+## Usage
+
+> DISCLAIMER 
+> 
+> `flatone` is designed for quick, exploratory inspection. Skeletons and warps are generated with the default parameters of `skeliner` and `pywarper`, most of them cannot be tuned directly in `flatone`, so results might not be optimal for some cells. For higher-precision results, run `skeliner` and `pywarper` directly and fine-tune the parameters.
+
+All you need to do is provide the segment ID of an EW2 neuron you'd like to preview: 
 
 ```bash
 flatone SEGMENT_ID
 ```
 
-(If you don't have a CAVEClient token yet, `flatone` will call `CAVEclient().auth.get_new_token()` automatically, which will guide you to a website to get a new token (you don't need to follow all the steps from the CAVEClient, you only need to go to the link, and get the token). After that, you can run `flatone add-token YOUR-NEW-TOKEN` to save it to the environment and then run `flatone SEGMENT_ID` again.)
+If you don't have a CAVEClient token stored in the system yet, `flatone` will call `CAVEclient().auth.get_new_token()` internally,  and prints something like:
 
-This creates an `output` directory in the working directory:
+```
+No CAVEclient token found.
+
+New Tokens need to be acquired by hand. Please follow the following steps:
+    1) Go to: https://<URL>
+    2) Log in with your Google account and copy the token shown.
+    3) Add it to Flatone with:
+    flatone add-token <TOKEN>
+    Note: ...
+    Warning! ...
+```
+
+Just follow the link, copy the token, and register it with:
+
+```bash
+flatone add-token <TOKEN>
+```
+
+The token is stored in `~/.cloudvolume/secrets`. Now you can rerun the command:
+
+```bash
+flatone SEGMENT_ID
+```
+
+This will create an `output` directory in the same directory:
 
 ```bash
 output
@@ -70,4 +103,3 @@ You can also warp the mesh, but it's not in the default as it's a much slower pr
 `flatone` also has a (limited) interactive 3d viewer, which you can activate via `flatone view3d`. You can append a SEGMENT_ID after it to just view this cell, or without it, to view all cells within the `output/` folder. By default, it will view the unwarped meshes and skeletons together, if you warped the mesh already, you can also view the warped meshes and skeletons with `flatone view3d --warped`. You can also curate a different set of cells in another folder, then view them with `flatone view3d --warped --output-dir="path/to/another/folder".
 
 Check `flatone -h` for more details.
-

flatone/cli.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 import argparse
+import io
 import re
 import sys
+from contextlib import redirect_stdout
 from importlib import resources
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
@@ -99,6 +101,44 @@ def _build_token_parser() -> argparse.ArgumentParser:
     p.add_argument("token", help="token string obtained from the DAF portal")
     return p
 
+def _prompt_for_token(client) -> None:
+    """
+    If the user has no token, show CaveClient’s instructions *minus* steps 3a/3b
+    and inject a Flatone-specific step 3.  Exits the program afterward.
+    """
+    if client.auth.token is not None:
+        return
+
+    print("No CAVEclient token found.\n")
+    # Capture CaveClient’s standard instructions without hard-coding them
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        client.auth.get_new_token()
+    cave_text = buf.getvalue().splitlines()
+
+    # Drop CaveClient’s “3a” and “3b” lines
+    filtered = [
+            ln for ln in cave_text
+            if not re.match(r'\s*3[ab]\)', ln)          # remove 3a/3b
+            and not re.match(r'\s*or\s*$', ln, re.I)    # remove “or”
+        ]
+    
+    # Insert our own single step 3 right after step 2
+    for idx, ln in enumerate(filtered):
+        if re.match(r'\s*2\)', ln):
+            filtered.insert(idx + 1,
+                "                3) Add it to `flatone` with:"
+            )
+            filtered.insert(idx + 2,
+                "                       flatone add-token <TOKEN>"
+            )
+            break
+
+    # Re-print the modified message and quit
+    print("\n".join(filtered))
+    raise SystemExit
+
+
 # ---------- pure functions ------------------------------------------------- #
 
 def fetch_mesh(seg_id: int, outdir: Path, verbose: bool, overwrite: bool) -> Path:
@@ -107,12 +147,8 @@ def fetch_mesh(seg_id: int, outdir: Path, verbose: bool, overwrite: bool) -> Pat
     # check caveclient credentials before proceeding
     from caveclient import CAVEclient
     client = CAVEclient()
-
-    if client.auth.token is None:
-        print("No CAVEclient token found.\n")
-        _ = client.auth.get_new_token()
-        raise SystemExit("\nRun `flatone add-token xxxxx` to add a token.")
-
+    _prompt_for_token(client)
+    
     mesh_path = outdir / "mesh.obj"
     if not overwrite and mesh_path.exists():
         if verbose:

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flatone"
-version = "0.1.9"
+version = "0.1.10"
 description = "A command-line tool to flatten one Eyewire2 neuron automatically."
 authors = []
 requires-python = ">=3.10.0"