| Name | wbsurfer2 JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | CLI tool for making CIFTI-related movies |
| upload_time | 2024-11-04 02:37:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License |
| keywords |
neuroimaging
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# wbsurfer2
CLI tool for making CIFTI-related movies
https://github.com/user-attachments/assets/e40315fb-f528-4cc7-ae91-8827bfef242c
This is a refactor and refresh of the original [wbsurfer](https://gitlab.com/vanandrew/wbsurfer) tool.
This version aims to support >= Connectome Workbench 2.0.
## Setup
There are two ways to use `wbsurfer2`. The first and recommended way is to
download compiled binaries from the [releases page](https://github.com/vanandrew/wbsurfer2/releases).
Simply download the version meant for your OS and extract it.
If you are more comfortable with Python, you can also install `wbsurfer2` from `pip`.
```bash
# install wbsurfer2 from PyPI
pip install wbsurfer2
# or if you want to install it for development
git clone git@github.com:vanandrew/wbsurfer2.git
cd wbsurfer2
pip install -e .
```
You will also need `ffmpeg` and `wb_command` installed on your system and on your `PATH`.
`wb_command` is part of the Connectome Workbench suite, which can be downloaded
[here](https://www.humanconnectome.org/software/get-connectome-workbench). The `bin` directory
contains the `wb_command` binary and should be added to your `PATH`.
> [!TIP]
> On macOS, the `wb_command` binary is located in the `Contents/usr/bin` directory of the
> Connectome Workbench installation. This is usually `/Applications/wb_view.app/Contents/usr/bin`.
```bash
# If you installed workbench in /opt/workbench
export PATH=$PATH:/opt/workbench/bin
# on macOS
export PATH=$PATH:/Applications/wb_view.app/Contents/usr/bin
```
`ffmpeg` can be downloaded in many ways, but I recommend using a package manager like `apt` or
[`brew`](https://brew.sh/):
```bash
# Ubuntu/Debian
sudo apt install ffmpeg
# macOS
brew install ffmpeg
```
## Usage
> [!IMPORTANT]
> `ffmpeg` and `wb_command` must be installed and on your `PATH` for `wbsurfer2` to work.
> Alternatively, you can specify the path to both programs using the `FFMPEG_BINARY_PATH` and `WBCOMMAND_BINARY_PATH`
> environment variables, if for some reason you are unable to add them to your `PATH`.
>
> `export FFMPEG_BINARY_PATH=/path/to/ffmpeg`
>
> `export WBCOMMAND_BINARY_PATH=/path/to/wb_command`
> [!TIP]
> If you are encountering an error with the scene rendering step, set `EXTERNAL_COMMAND_LOG=1` in your
> environment for more verbose details on what is happening to the `wb_command`.
Once it's installed, you can run the `wb_surfer2` command. The following is the help message:
```bash
usage: wb_surfer2 [-h] [-v] -s SCENE_PATH -n SCENE_NAME -o OUTPUT [--width WIDTH] [--height HEIGHT]
[-r FRAMERATE] [--closed | --reverse] [-l LOOPS] [--num-cpus NUM_CPUS]
[--vertex-mode | --border-file]
row_indices [row_indices ...]
Generate a movie from a list of row indices.
positional arguments:
row_indices The list of row indices to generate the movie from.
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
-s SCENE_PATH, --scene-path SCENE_PATH
The scene file to use.
-n SCENE_NAME, --scene-name SCENE_NAME
The name of the scene in the scene file.
-o OUTPUT, --output OUTPUT
The output file path. Should end in .mp4.
--width WIDTH The width of the output movie. By default, 1920 pixels.
--height HEIGHT The height of the output movie. By default, 1080 pixels.
-r FRAMERATE, --framerate FRAMERATE
The framerate of the output movie. By default, 10 FPS.
--closed If enabled, a closed loop will be generated. This appends the first row index to
the end of the row index traversal list. Mutually exclusive with --reverse.
--reverse If enabled, a reverse of the traversal list will be appended to the row index
traversal list. Mutually exclusive with --closed.
-l LOOPS, --loops LOOPS
How many times to loop the movie. By default, 1 loop.
--num-cpus NUM_CPUS The number of CPUs to use for processing.
--vertex-mode If enabled, row_indices are treated as vertex indices. The first argument should
be the surface that the vertices are on. Mutually exclusive with --border-file
(e.g. CORTEX_LEFT 0 1 2 3...)
--border-file If enabled, the border file will be used to generate the movie. The row_indices
argument should be the border file. Mutually exclusive with --vertex-mode.
```
> [!TIP]
> Row indices passed into `wb_surfer2` are 0-indexed. This means that the first row is row 0,
> the second row is row 1, and so on. This is -1 from the row indices given in the UI of Connectome Workbench.
`wb_surfer2` requires a scene file to generate the movie. This scene file can be created in Connectome Workbench's
`wb_view` tool.
Unlike in version 1 of `wb_surfer`, `wb_surfer2` can handle multiple scenes being defined in a file (though only one
active scene can be used at a time). The active scene is set by using the `--scene-name` argument.
When making your scene, at least one vertex must be placed on the surface for `wb_surfer2` to control. In the case of
multiple vertices, the first vertex that was placed will be manipulated.
Raw data
{
"_id": null,
"home_page": null,
"name": "wbsurfer2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "neuroimaging",
"author": null,
"author_email": "Andrew Van <vanandrew77@gmail.com>",
"download_url": null,
"platform": null,
"description": "# wbsurfer2\nCLI tool for making CIFTI-related movies\n\nhttps://github.com/user-attachments/assets/e40315fb-f528-4cc7-ae91-8827bfef242c\n\nThis is a refactor and refresh of the original [wbsurfer](https://gitlab.com/vanandrew/wbsurfer) tool.\nThis version aims to support >= Connectome Workbench 2.0.\n\n## Setup\n\nThere are two ways to use `wbsurfer2`. The first and recommended way is to\ndownload compiled binaries from the [releases page](https://github.com/vanandrew/wbsurfer2/releases).\nSimply download the version meant for your OS and extract it.\n\nIf you are more comfortable with Python, you can also install `wbsurfer2` from `pip`.\n\n```bash\n# install wbsurfer2 from PyPI\npip install wbsurfer2\n\n# or if you want to install it for development\ngit clone git@github.com:vanandrew/wbsurfer2.git\ncd wbsurfer2\npip install -e .\n```\n\nYou will also need `ffmpeg` and `wb_command` installed on your system and on your `PATH`.\n\n`wb_command` is part of the Connectome Workbench suite, which can be downloaded\n[here](https://www.humanconnectome.org/software/get-connectome-workbench). The `bin` directory\ncontains the `wb_command` binary and should be added to your `PATH`.\n\n> [!TIP]\n> On macOS, the `wb_command` binary is located in the `Contents/usr/bin` directory of the\n> Connectome Workbench installation. This is usually `/Applications/wb_view.app/Contents/usr/bin`.\n\n```bash\n# If you installed workbench in /opt/workbench\nexport PATH=$PATH:/opt/workbench/bin\n\n# on macOS\nexport PATH=$PATH:/Applications/wb_view.app/Contents/usr/bin\n```\n\n`ffmpeg` can be downloaded in many ways, but I recommend using a package manager like `apt` or\n [`brew`](https://brew.sh/):\n\n```bash\n# Ubuntu/Debian\nsudo apt install ffmpeg\n\n# macOS\nbrew install ffmpeg\n```\n\n## Usage\n\n> [!IMPORTANT] \n> `ffmpeg` and `wb_command` must be installed and on your `PATH` for `wbsurfer2` to work.\n> Alternatively, you can specify the path to both programs using the `FFMPEG_BINARY_PATH` and `WBCOMMAND_BINARY_PATH`\n> environment variables, if for some reason you are unable to add them to your `PATH`.\n>\n> `export FFMPEG_BINARY_PATH=/path/to/ffmpeg`\n>\n> `export WBCOMMAND_BINARY_PATH=/path/to/wb_command`\n\n> [!TIP]\n> If you are encountering an error with the scene rendering step, set `EXTERNAL_COMMAND_LOG=1` in your\n> environment for more verbose details on what is happening to the `wb_command`.\n\nOnce it's installed, you can run the `wb_surfer2` command. The following is the help message:\n\n```bash\nusage: wb_surfer2 [-h] [-v] -s SCENE_PATH -n SCENE_NAME -o OUTPUT [--width WIDTH] [--height HEIGHT]\n [-r FRAMERATE] [--closed | --reverse] [-l LOOPS] [--num-cpus NUM_CPUS]\n [--vertex-mode | --border-file]\n row_indices [row_indices ...]\n\nGenerate a movie from a list of row indices.\n\npositional arguments:\n row_indices The list of row indices to generate the movie from.\n\noptions:\n -h, --help show this help message and exit\n -v, --version show program's version number and exit\n -s SCENE_PATH, --scene-path SCENE_PATH\n The scene file to use.\n -n SCENE_NAME, --scene-name SCENE_NAME\n The name of the scene in the scene file.\n -o OUTPUT, --output OUTPUT\n The output file path. Should end in .mp4.\n --width WIDTH The width of the output movie. By default, 1920 pixels.\n --height HEIGHT The height of the output movie. By default, 1080 pixels.\n -r FRAMERATE, --framerate FRAMERATE\n The framerate of the output movie. By default, 10 FPS.\n --closed If enabled, a closed loop will be generated. This appends the first row index to\n the end of the row index traversal list. Mutually exclusive with --reverse.\n --reverse If enabled, a reverse of the traversal list will be appended to the row index\n traversal list. Mutually exclusive with --closed.\n -l LOOPS, --loops LOOPS\n How many times to loop the movie. By default, 1 loop.\n --num-cpus NUM_CPUS The number of CPUs to use for processing.\n --vertex-mode If enabled, row_indices are treated as vertex indices. The first argument should\n be the surface that the vertices are on. Mutually exclusive with --border-file\n (e.g. CORTEX_LEFT 0 1 2 3...)\n --border-file If enabled, the border file will be used to generate the movie. The row_indices\n argument should be the border file. Mutually exclusive with --vertex-mode.\n ```\n\n> [!TIP]\n> Row indices passed into `wb_surfer2` are 0-indexed. This means that the first row is row 0,\n> the second row is row 1, and so on. This is -1 from the row indices given in the UI of Connectome Workbench.\n\n`wb_surfer2` requires a scene file to generate the movie. This scene file can be created in Connectome Workbench's\n`wb_view` tool.\n\nUnlike in version 1 of `wb_surfer`, `wb_surfer2` can handle multiple scenes being defined in a file (though only one\nactive scene can be used at a time). The active scene is set by using the `--scene-name` argument.\n\nWhen making your scene, at least one vertex must be placed on the surface for `wb_surfer2` to control. In the case of\nmultiple vertices, the first vertex that was placed will be manipulated. \n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "CLI tool for making CIFTI-related movies",
"version": "0.2.2",
"project_urls": {
"github": "https://github.com/vanandrew/wbsurfer2"
},
"split_keywords": [
"neuroimaging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "09b1305bba4d1eafff0f66e1026db7cc06996bbd36291a314978a2c559ea6ee0",
"md5": "0ce2cee865c8ed4bce13c81c0e591e70",
"sha256": "6b482b5d44cb621c2064b70999160131de80de9e1064f1d49ea0f7460cfbd12d"
},
"downloads": -1,
"filename": "wbsurfer2-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ce2cee865c8ed4bce13c81c0e591e70",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18627,
"upload_time": "2024-11-04T02:37:13",
"upload_time_iso_8601": "2024-11-04T02:37:13.237388Z",
"url": "https://files.pythonhosted.org/packages/09/b1/305bba4d1eafff0f66e1026db7cc06996bbd36291a314978a2c559ea6ee0/wbsurfer2-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-04 02:37:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vanandrew",
"github_project": "wbsurfer2",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wbsurfer2"
}
