From 01671bfda0757416564c7c70ae32d8a290db1117 Mon Sep 17 00:00:00 2001 From: FreddyFunk <27208977+FreddyFunk@users.noreply.github.com> Date: Thu, 27 Jul 2023 13:50:44 +0200 Subject: [PATCH] switch from asciidoc to mdbook --- .github/workflows/asciidoc-ghpages.yml | 28 --------------------- .github/workflows/publish-ghpages.yml | 35 ++++++++++++++++++++++++++ .gitignore | 19 ++++++++++++++ book.toml | 6 +++++ chapter-1.adoc | 11 -------- chapter-2.adoc | 14 ----------- index.adoc | 14 ----------- src/SUMMARY.md | 7 ++++++ src/development.md | 33 ++++++++++++++++++++++++ src/importing_static_volume_data.md | 3 +++ src/introduction.md | 7 ++++++ src/supported_plattforms.md | 14 +++++++++++ src/visualization.md | 3 +++ 13 files changed, 127 insertions(+), 67 deletions(-) delete mode 100644 .github/workflows/asciidoc-ghpages.yml create mode 100644 .github/workflows/publish-ghpages.yml create mode 100644 .gitignore create mode 100644 book.toml delete mode 100644 chapter-1.adoc delete mode 100644 chapter-2.adoc delete mode 100644 index.adoc create mode 100644 src/SUMMARY.md create mode 100644 src/development.md create mode 100644 src/importing_static_volume_data.md create mode 100644 src/introduction.md create mode 100644 src/supported_plattforms.md create mode 100644 src/visualization.md diff --git a/.github/workflows/asciidoc-ghpages.yml b/.github/workflows/asciidoc-ghpages.yml deleted file mode 100644 index 42eeae5..0000000 --- a/.github/workflows/asciidoc-ghpages.yml +++ /dev/null @@ -1,28 +0,0 @@ -name: asciidoctor-ghpages - -# Controls when the action will run. Triggers the workflow on push or pull request -# events but only for the master branch -on: - push: - branches: [ main ] - -permissions: - contents: write # for committing to gh-pages branch. - -# A workflow run is made up of one or more jobs that can run sequentially or in parallel -jobs: - # This workflow contains a single job called "build" - build: - # The type of runner that the job will run on - runs-on: ubuntu-latest - - # Steps represent a sequence of tasks that will be executed as part of the job - steps: - # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - - uses: actions/checkout@v2 - - - name: asciidoctor-ghpages - uses: manoelcampos/asciidoctor-ghpages-action@v2 - with: - asciidoctor_params: --attribute=nofooter - # pdf_build: true \ No newline at end of file diff --git a/.github/workflows/publish-ghpages.yml b/.github/workflows/publish-ghpages.yml new file mode 100644 index 0000000..c4b97b6 --- /dev/null +++ b/.github/workflows/publish-ghpages.yml @@ -0,0 +1,35 @@ +name: mdbook-ghpages + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the master branch +on: + push: + branches: [ main ] + +permissions: + contents: write # for committing to gh-pages branch. + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v2 + - name: Rust Cache # cache the rust build artefacts + uses: Swatinem/rust-cache@v1 + - name: Install mdbook + run: cargo install mdbook + - name: Build # build + run: mkbook build + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: book + # this option will not maintain any history of your previous pages deployment + # set to false if you want all page build to be committed to your gh-pages branch history + single-commit: true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..f2e9d3a --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +target + +# MacOS temp file +.DS_Store + +book +book-test +guide/book + +.vscode +tests/dummy_book/book/ +test_book/book/ + +# Ignore Jetbrains specific files. +.idea/ + +# Ignore Vim temporary and swap files. +*.sw? +*~ diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..7e53ec1 --- /dev/null +++ b/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["FreddyFunk"] +language = "en" +multilingual = false +src = "src" +title = "Volume Data Suite Documentation" diff --git a/chapter-1.adoc b/chapter-1.adoc deleted file mode 100644 index cd90105..0000000 --- a/chapter-1.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Chapter Title - -A paragraph with *bold* and _italic_ text. - -.Image title -image::an-image.jpg[align=center] - -The `xref` macro is used for source-to-source links, like xref:a-book.adoc[]. -An external link to https://eclipse.org[Eclipse]. - -NOTE: One of five built-in admonition block types. \ No newline at end of file diff --git a/chapter-2.adoc b/chapter-2.adoc deleted file mode 100644 index b935475..0000000 --- a/chapter-2.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Another Chapter Title - - Text indented by one space is preformatted. - -The following source code block contains a Ruby function named `hello` that prints "`Hello, World!`". - -[%linenums,ruby] ----- -def hello name = 'World' - puts "Hello, #{name}!" -end ----- - -That's all she wrote! \ No newline at end of file diff --git a/index.adoc b/index.adoc deleted file mode 100644 index 19bb8d6..0000000 --- a/index.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Book Title -Doc Writer -v2.0.1, 2022-01-15 -:doctype: book -:front-cover-image: cover.png[,1050,1600] - -[preface] -== Preface - -The story behind the story. - -include::chapter-1.adoc[leveloffset=1] - -include::chapter-2.adoc[leveloffset=1] diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..a09193a --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +- [Introduction](./introduction.md) +- [Supported Plattforms](./supported_plattforms.md) +- [Importing Static Volume Data](./importing_static_volume_data.md) +- [Visualization](./visualization.md) +- [Development](./development.md) diff --git a/src/development.md b/src/development.md new file mode 100644 index 0000000..2e0ba9f --- /dev/null +++ b/src/development.md @@ -0,0 +1,33 @@ +# Development +VDS is written in [Rust](https://www.rust-lang.org/) and shaders are written in [WGSL](https://www.w3.org/TR/WGSL/). + +Make sure you are using the latest version of stable rust by running `rustup update`. VDS requires a proper graphics driver that provides at least one of the [supported graphics APIs](#cross-platform-support). + +## Building from Source for Native + +Run it locally with `cargo run --release`. + +On Linux you need to first run: + +`sudo apt-get install libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev libssl-dev` + +On Fedora Rawhide you need to run: + +`dnf install clang clang-devel clang-tools-extra libxkbcommon-devel pkg-config openssl-devel libxcb-devel gtk3-devel atk fontconfig-devel` + +## Building from Source for Web + +[Trunk](https://trunkrs.dev/) can be used to compile `vds` to WASM and spin up a web server with hot reloading. + +1. Install Trunk with `cargo install --locked trunk`. +2. Run `trunk serve` to build and serve on `http://127.0.0.1:8080`. Trunk will rebuild automatically if you edit the project. +3. Open `http://127.0.0.1:8080/index.html#dev` in a browser. See the warning below. + +> `assets/sw.js` script will try to cache our VDS app, and loads the cached version when it cannot connect to server allowing VDS to work offline (like PWA). +> appending `#dev` to `index.html` will skip this caching, allowing to load the latest builds during development. + +## Deploy for Web +1. Just run `trunk build --release`. +2. It will generate a `dist` directory as a "static html" website +3. Upload the `dist` directory to any of the numerous free hosting websites including [GitHub Pages](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site). +4. This repo already provides a [workflow](.github/workflows/deploy_github_pages.yml) that auto-deploys VDS to GitHub pages. diff --git a/src/importing_static_volume_data.md b/src/importing_static_volume_data.md new file mode 100644 index 0000000..1833891 --- /dev/null +++ b/src/importing_static_volume_data.md @@ -0,0 +1,3 @@ +# Importing Static Volume Data +Currenltly the following file formats can be imported: +- RAW 3D \ No newline at end of file diff --git a/src/introduction.md b/src/introduction.md new file mode 100644 index 0000000..ec564a9 --- /dev/null +++ b/src/introduction.md @@ -0,0 +1,7 @@ +# Introduction +Volume Data Suite (VDS) is a free and open source app that can be used to visualize and interact with volumetric image data. + +View the web demo app online at or download the [latest native version](https://github.com/Volume-Data-Suite/vds/releases) for your plattform. + +## Status +VDS is currently nothing more than a proof of concept and in a very early pre-alpha state. There are many features I want to add, and the API and User Interface is still evolving. _Expect breaking changes!_ \ No newline at end of file diff --git a/src/supported_plattforms.md b/src/supported_plattforms.md new file mode 100644 index 0000000..547bacc --- /dev/null +++ b/src/supported_plattforms.md @@ -0,0 +1,14 @@ +# Supported Plattforms +## Cross-Platform Support +Currently the following graphics APIs are supported: +- Windows (Vulkan and DirectX) +- macOS (Metal) +- Linux (Vulkan) +- Web (WebGPU) + +## Web Plattform restrictions: +**_WebGL_** is currrently not supported due to significant performance reductions. Make sure that you use the latest version of your web browser and check its **_WebGPU_** support, if you want to use the web based version of VDS. The latest versions of Chromium based browsers like Google Chrome, Microsoft Edge and Chromium itself should work. + +**_Direct file system access_** is currently [not possible](https://stackoverflow.com/questions/71017592/can-i-read-files-from-the-disk-by-using-webassembly-re-evaluated) with WebAssembly (WASM). Therefore files can only be opened via drag and drop or by downloading them from a URL and not all file types are supported. Files can only be exported as a download. + +**_Gerneral Perfomance_** is better on native versions of VDS that run directly on the operating system and not inside a web browser. Main reason are missing [SIMD](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data) like _f16c_ on x86 or _fp16_ on arm64 which are not available in WASM. \ No newline at end of file diff --git a/src/visualization.md b/src/visualization.md new file mode 100644 index 0000000..f79e806 --- /dev/null +++ b/src/visualization.md @@ -0,0 +1,3 @@ +# Visualization +Currently the volume data can be visualized as: +- 2D Slices (X-Axis only) \ No newline at end of file