From e14f4a74303ca3d1713816c2df10188beb5b8081 Mon Sep 17 00:00:00 2001 From: Miles Graham Date: Tue, 11 Jun 2024 09:16:34 +0100 Subject: [PATCH] Added doc pages using mkdocs. Have also added mkdocs-video in the hope that I will incorporate some nice chimera movies as examples to the page at some point. --- docs/examples/cone.md | 27 +++++++++++++++++ docs/examples/cube.md | 25 ++++++++++++++++ docs/examples/cuboid.md | 25 ++++++++++++++++ docs/examples/cylinder.md | 25 ++++++++++++++++ docs/examples/ellipsoid.md | 25 ++++++++++++++++ docs/examples/sphere.md | 25 ++++++++++++++++ docs/overview.md | 44 ++++++++++++++++++++++++++++ mkdocs.yml | 60 ++++++++++++++++++++++++++++++++++++++ pyproject.toml | 2 ++ 9 files changed, 258 insertions(+) create mode 100644 docs/examples/cone.md create mode 100644 docs/examples/cube.md create mode 100644 docs/examples/cuboid.md create mode 100644 docs/examples/cylinder.md create mode 100644 docs/examples/ellipsoid.md create mode 100644 docs/examples/sphere.md create mode 100644 docs/overview.md create mode 100644 mkdocs.yml diff --git a/docs/examples/cone.md b/docs/examples/cone.md new file mode 100644 index 0000000..fd62175 --- /dev/null +++ b/docs/examples/cone.md @@ -0,0 +1,27 @@ +# Cone + +To view the available options for the cone command, make use of the '--help' provision. + +```shell + +ttmask cone --help + +``` + +## Commands and Options + +Option | Usage | +------------ |-----------------------------------------------------------------------------------| +--sidelength | This specifies the your box size. e.g. a 100 x 100 x 100 pixel array. | +--cone-height | The height of your cone in angstrom. | +--cone-base-diameter | The diameter of the base (i.e. widest diameter) of the cone. +--soft-edge-width | The number of pixels over which a soft edge will be added. | +--pixel-size | The desired pixel size of your output. If left blank, 1 will be taken as default. | +--output | Name of your output file, e.g. cone1.mrc | + +Note : Currently hollow cones are not available due to some quirks as to how this needs to be specified. + + + + + \ No newline at end of file diff --git a/docs/examples/cube.md b/docs/examples/cube.md new file mode 100644 index 0000000..fa07586 --- /dev/null +++ b/docs/examples/cube.md @@ -0,0 +1,25 @@ +# Cube + +To view the available options for the cube command, make use of the '--help' provision. + +```shell + +ttmask cube --help + +``` + +## Commands and Options + +Option | Usage | +------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +--sidelength | This specifies the your box size. e.g. a 100 x 100 x 100 pixel array. | +--cube-sidelength | The edge length of your cube in angstrom. | +--soft-edge-width | The number of pixels over which a soft edge will be added. | +--pixel-size | The desired pixel size of your output. If left blank, 1 will be taken as default. | +--output | Name of your output file, e.g. cube5.mrc | +--wall-thickness | If specified (in angstrom), the cube will be hollow. The walls of the cube will be given this thickness, but will be added inwards of the boundary, such that cube-sidelength dimensions are not exceeded. | + + + + + \ No newline at end of file diff --git a/docs/examples/cuboid.md b/docs/examples/cuboid.md new file mode 100644 index 0000000..17811d0 --- /dev/null +++ b/docs/examples/cuboid.md @@ -0,0 +1,25 @@ +# Cuboid + +To view the available options for the cuboid command, make use of the '--help' provision. + +```shell + +ttmask cuboid --help + +``` + +## Commands and Options + +Option | Usage | +------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +--sidelength | This specifies the your box size. e.g. a 100 x 100 x 100 pixel array. | +--cuboid-sidelengths | The edge lengths of your cuboid in angstrom, specied as three space seperated floats e.g. 50 50 50. These correspond to the depth, height and width of your cuboid respectively (i.e. zyx) | +--soft-edge-width | The number of pixels over which a soft edge will be added. | +--pixel-size | The desired pixel size of your output. If left blank, 1 will be taken as default. | +--output | Name of your output file, e.g. cuboid5.mrc | +--wall-thickness | If specified (in angstrom), the cuboid will be hollow. The walls of the cube will be given this thickness, but will be added inwards of the boundary, such that cuboid-sidelengths dimensions are not exceeded. | + + + + + \ No newline at end of file diff --git a/docs/examples/cylinder.md b/docs/examples/cylinder.md new file mode 100644 index 0000000..4f18d4a --- /dev/null +++ b/docs/examples/cylinder.md @@ -0,0 +1,25 @@ +# Cylinder + +To view the available options for the cylinder command, make use of the '--help' provision. + +```shell + +ttmask cylinder --help + +``` + +## Commands and Options + +Option | Usage | +------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +--sidelength | This specifies the your box size. e.g. a 100 x 100 x 100 pixel array. | +--cylinder-diameter | The diameter of your cylinder in angstrom, measured from outermost edge to edge. | +--soft-edge-width | The number of pixels over which a soft edge will be added. | +--pixel-size | The desired pixel size of your output. If left blank, 1 will be taken as default. | +--output | Name of your output file, e.g. cyl1.mrc | +--wall-thickness | If specified (in angstrom), the cylinder will be hollow, with this thickness wall. The thickness is not added to the cylinder-diameter, but instead is added inward of that boundary such that your specified diameter still remains accurate. | + + + + + \ No newline at end of file diff --git a/docs/examples/ellipsoid.md b/docs/examples/ellipsoid.md new file mode 100644 index 0000000..3759829 --- /dev/null +++ b/docs/examples/ellipsoid.md @@ -0,0 +1,25 @@ +# Ellipsoid + +To view the available options for the ellipsoid command, make use of the '--help' provision. + +```shell + +ttmask ellipsoid --help + +``` + +## Commands and Options + +Option | Usage | +------------ |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +--sidelength | This specifies the your box size. e.g. a 100 x 100 x 100 pixel array. | +--ellipsoid-dimensions | The lengths of your ellipsoid in angstrom, specied as three space seperated floats e.g. 50 30 30. These correspond to the depth, height and width of your ellipsoid respectively (i.e. zyx) | +--soft-edge-width | The number of pixels over which a soft edge will be added. | +--pixel-size | The desired pixel size of your output. If left blank, 1 will be taken as default. | +--output | Name of your output file, e.g. ellipsoid1.mrc | +--wall-thickness | If specified (in angstrom), the ellipsoid will be hollow, with this thickness wall. The thickness is not added to the ellipsoid-dimensions, but instead is added inward of that boundary such that your specified dimensions still remain accurate. | + + + + + \ No newline at end of file diff --git a/docs/examples/sphere.md b/docs/examples/sphere.md new file mode 100644 index 0000000..919f25a --- /dev/null +++ b/docs/examples/sphere.md @@ -0,0 +1,25 @@ +# Sphere + +To view the available options for the sphere command, make use of the '--help' provision. + +```shell + +ttmask sphere --help + +``` + +## Commands and Options + +Option | Usage | +------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +--sidelength | This specifies the your box size. e.g. a 100 x 100 x 100 pixel array. | +--sphere-diameter | The diameter of your sphere in angstrom, measured from outermost edge to edge. | +--soft-edge-width | The number of pixels over which a soft edge will be added. | +--pixel-size | The desired pixel size of your output. If left blank, 1 will be taken as default. | +--output | Name of your output file, e.g. sphere5.mrc | +--wall-thickness | If specified (in angstrom), the sphere will be hollow, with this thickness wall. The thickness is not added to the sphere-diameter, but instead is added inward of that boundary such that your specified diameter still remains accurate. | + + + + + \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..235c78f --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,44 @@ +# Overview + +*ttmask* is a Python package for generating masks and references for cryo-EM data analysis. + +*ttmask* can be used to create masks of various geometries, or from existing cryo-EM maps. + +--- +# Installation +The package is available for download via pip. + +```shell + +pip install ttmask + +``` +# Quickstart + +To view the available options in ttmask and understand which parameters are required, make use of the '--help' provision. + +```shell + +ttmask --help + +``` +Then choose the command you desire and fill in the options, like so : + +```shell + +ttmask cylinder --sidelength 200 --pixel-size 0.5 --cylinder-height 60 --cylinder-diameter 20 + +``` + +In this example, we have generated a cylinder 60 angstrom height and 20 angstrom across, in a 200 x 200 x 200 pixel box at 0.5 angstrom per pixel. + +Now we could think about making the cylindrical mask hollow and adding a soft edge to the mask : + + +```shell + +ttmask cylinder --sidelength 200 --pixel-size 0.5 --cylinder-height 60 --cylinder-diameter 20 --soft-edge-width 3 --wall-thickness 3 + +``` + +[//]: # (![type:video](./videos/costa_rica.mp4)) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..62a8844 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,60 @@ +site_name: teamtomo/ttmask +site_url: https://teamtomo.org/ttmask +site_author: teamtomo +site_description: >- + Documentation for ttmask +repo_name: teamtomo/ttmask +repo_url: https://github.com/teamtomo/ttmask +edit_uri: edit/main/docs/ +copyright: Copyright © 2022 - 2022 teamtomo + + +# Custom navigation can be specified +nav: + - Overview: overview.md + - Examples: + + - Cone: examples/cone.md + - Cube: examples/cube.md + - Cuboid: examples/cuboid.md + - Cylinder: examples/cylinder.md + - Ellipsoid: examples/ellipsoid.md + - Sphere: examples/sphere.md +theme: + icon: + logo: material/cube-outline + name: material + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: blue + accent: blue + + features: + - navigation.instant + - navigation.expand + - search.highlight + - search.suggest + - content.tabs.link + +markdown_extensions: + - admonition + - tables + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - attr_list + - pymdownx.superfences + - pymdownx.highlight + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + - md_in_html + - pymdownx.arithmatex: + generic: true + +plugins: + - search + - mkdocs-video \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 2fb5965..4909cd4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,6 +56,8 @@ dev = [ "pre-commit", "rich", # https://github.com/Textualize/rich "ruff", + "mkdocs-material", + "mkdocs-video" ] [project.urls]