From 93a3d7c8aef196e0195e4d8cf1804170e2760dc7 Mon Sep 17 00:00:00 2001 From: AlgoFoe Date: Mon, 15 Jun 2026 22:23:19 +0530 Subject: [PATCH 1/6] docs: improve numpy-style docstrings in render module --- brainrender/render.py | 168 +++++++++++++++++++++++++++++------------- 1 file changed, 115 insertions(+), 53 deletions(-) diff --git a/brainrender/render.py b/brainrender/render.py index 6072ef77..98e232b6 100644 --- a/brainrender/render.py +++ b/brainrender/render.py @@ -1,6 +1,10 @@ from datetime import datetime from pathlib import Path +from __future__ import annotations + +from typing import TYPE_CHECKING + import numpy as np from loguru import logger from myterial import teal @@ -17,6 +21,8 @@ get_camera, set_camera, ) +if TYPE_CHECKING: + from brainrender.actor import Actor # mtx used to transform meshes to sort axes orientation mtx = [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, -1, 0], [0, 0, 0, 1]] @@ -31,10 +37,14 @@ class Render: axes_lookup = {"x": "AP", "y": "DV", "z": "LR"} axes_indices = {"AP": 0, "DV": 1, "LR": 2} - def __init__(self, plotter=None): + def __init__(self, plotter: Plotter | None = None) -> None: """ - Backend for Scene, handles all rendering and exporting - related tasks. + Backend for Scene, handles all rendering and exporting related tasks. + + Parameters + ---------- + plotter + Existing vedo Plotter to use. A new one is created if None. """ if plotter is None: self._get_plotter() @@ -42,10 +52,9 @@ def __init__(self, plotter=None): self.plotter = plotter self.plotter.keyPressFunction = self.keypress - def _get_plotter(self): + def _get_plotter(self) -> None: """ - Make a vedo plotter with - fancy axes and all + Instantiate a vedo Plotter with custom axes and settings. """ self.plotter = Plotter( axes=self._make_axes() if settings.SHOW_AXES else None, @@ -58,10 +67,14 @@ def _get_plotter(self): self.plotter.keyPressFunction = self.keypress - def _make_axes(self): + def _make_axes(self) -> dict: """ - Returns a dictionary with axes - parameters for the vedo plotter + Build a custom axes parameter dict for the vedo Plotter. + + Returns + ------- + dict + Axes configuration passed directly to vedo. """ ax_idx = self.atlas.space.axes_order.index("frontal") @@ -110,13 +123,18 @@ def _make_axes(self): return axes - def _prepare_actor(self, actor): + def _prepare_actor(self, actor: Actor) -> None: """ - When an actor is first rendered, a transform matrix - is applied to its points to correct axes orientation - mismatches: https://github.com/brainglobe/brainglobe-atlasapi/issues/73 + Apply axis-orientation transform to an actor on first render. - Once an actor is 'corrected' it spawns labels and silhouettes as needed + Corrects axes orientation mismatches (see + https://github.com/brainglobe/brainglobe-atlasapi/issues/73), + then spawns any pending labels and silhouettes. + + Parameters + ---------- + actor + Actor to prepare. """ # don't apply transforms to points density actors if isinstance(actor, PointsDensity): @@ -163,9 +181,9 @@ def _prepare_actor(self, actor): if actor._needs_label and not self.backend: self.labels.extend(actor.make_label(self.atlas)) - def _apply_style(self): + def _apply_style(self) -> None: """ - Sets the rendering style for each mesh + Set the rendering style for each mesh. """ for actor in self.clean_actors: if settings.SHADER_STYLE != "cartoon": @@ -188,24 +206,29 @@ def _apply_style(self): def render( self, - interactive=None, - camera=None, - zoom=None, - resetcam=False, - **kwargs, - ): + interactive: bool | None = None, + camera: str | dict | None = None, + zoom: float | None = None, + resetcam: bool = False, + **kwargs: object, + ) -> None: """ - Renders the scene. - - :param interactive: bool. If note settings.INTERACTIVE is used. - If true the program's execution is stopped and users - can interact with scene. - :param camera: str, dict. If none the default camera is used. - Pass a valid camera input to specify the camera position when - the scene is rendered. - :param zoom: float, if None atlas default is used - :param resetcam: bool, if True the camera is reset between renders - :param kwargs: additional arguments to pass to self.plotter.show + Render the scene. + + Parameters + ---------- + interactive + If None, falls back to ``settings.INTERACTIVE``. When True, + execution pauses so the user can interact with the scene. + camera + Camera name or parameter dict. Falls back to + ``settings.DEFAULT_CAMERA`` if None. + zoom + Camera zoom level. Falls back to the atlas default if None. + resetcam + Reset the camera between renders. + **kwargs + Additional arguments forwarded to ``self.plotter.show``. """ logger.debug( f"Rendering scene. Interactive: {interactive}, camera: {camera}, zoom: {zoom}" @@ -290,15 +313,32 @@ def render( sep="\n", ) - def close(self): + def close(self) -> None: + """ + Close the vedo Plotter window. + """ self.plotter.close() - def export(self, savepath, **kwargs): + def export(self, savepath: str | Path, **kwargs: object) -> str: """ - Exports the scene to a .html - file for online renderings. - - :param savepath: str, Path to a .html file to save the export + Export the scene to a ``.html`` file for online rendering. + + Parameters + ---------- + savepath + Path to the output ``.html`` file. + **kwargs + Additional arguments forwarded to :meth:`render`. + + Returns + ------- + str + Absolute path of the saved file. + + Raises + ------ + ValueError + If *savepath* does not have a ``.html`` suffix. """ logger.debug(f"Exporting scene to {savepath}") _backend = self.backend @@ -332,17 +372,33 @@ def export(self, savepath, **kwargs): return str(path) - def screenshot(self, name=None, scale=None, **kwargs): + def screenshot( + self, + name: str | None = None, + scale: float | None = None, + **kwargs: object, + ) -> str: """ - Takes a screenshot of the current view - and save it to file. - Screenshots are saved in `screenshots_folder` - (see Scene) - - :param name: str, name of png file - :param scale: float, >1 for higher resolution + Take a screenshot of the current view and save it to file. + + Screenshots are saved in ``screenshots_folder`` (see Scene). + + Parameters + ---------- + name + Output filename. Defaults to a timestamped ``.png`` if None. + Unsupported extensions are silently replaced with ``.png``. + scale + Resolution multiplier. Values above 1 increase resolution. + Falls back to ``settings.SCREENSHOT_SCALE`` if None. + **kwargs + Additional arguments forwarded to :meth:`render`. + + Returns + ------- + str + Absolute path of the saved screenshot. """ - if not self.is_rendered: self.render(interactive=False, **kwargs) @@ -362,12 +418,18 @@ def screenshot(self, name=None, scale=None, **kwargs): self.plotter.screenshot(filename=savepath, scale=scale) return savepath - def keypress(self, key): # pragma: no cover + def keypress(self, key: str) -> None: # pragma: no cover """ - Handles key presses for interactive view - -s: take's a screenshot - -q: closes the window - -c: prints the current camera parameters + Handle key presses during interactive rendering. + + - ``s``: take a screenshot + - ``q`` / ``Esc``: close the window + - ``c``: print current camera parameters + + Parameters + ---------- + key + Key identifier string from vedo. """ if key == "s": self.screenshot() From 94df25e5c2585ae9af045c3335454f75ef0d8ce9 Mon Sep 17 00:00:00 2001 From: AlgoFoe Date: Mon, 15 Jun 2026 22:24:03 +0530 Subject: [PATCH 2/6] add module level docstring --- brainrender/render.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/brainrender/render.py b/brainrender/render.py index 98e232b6..62920917 100644 --- a/brainrender/render.py +++ b/brainrender/render.py @@ -1,3 +1,5 @@ +"""Scene rendering backend for brainrender.""" + from datetime import datetime from pathlib import Path From 416df6fbacc1a7051309d6d49176331279e4a418 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 15 Jun 2026 16:56:49 +0000 Subject: [PATCH 3/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- brainrender/render.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/brainrender/render.py b/brainrender/render.py index 62920917..1d7ff519 100644 --- a/brainrender/render.py +++ b/brainrender/render.py @@ -1,10 +1,9 @@ """Scene rendering backend for brainrender.""" -from datetime import datetime -from pathlib import Path - from __future__ import annotations +from datetime import datetime +from pathlib import Path from typing import TYPE_CHECKING import numpy as np @@ -23,6 +22,7 @@ get_camera, set_camera, ) + if TYPE_CHECKING: from brainrender.actor import Actor From 3334e41b865dda2a4f176f93376659b3d50825f7 Mon Sep 17 00:00:00 2001 From: AlgoFoe Date: Mon, 22 Jun 2026 21:55:38 +0530 Subject: [PATCH 4/6] update typehint for **kwargs to Any --- brainrender/render.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/brainrender/render.py b/brainrender/render.py index 62920917..d2388c2b 100644 --- a/brainrender/render.py +++ b/brainrender/render.py @@ -5,7 +5,7 @@ from __future__ import annotations -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Any import numpy as np from loguru import logger @@ -212,7 +212,7 @@ def render( camera: str | dict | None = None, zoom: float | None = None, resetcam: bool = False, - **kwargs: object, + **kwargs: Any, ) -> None: """ Render the scene. @@ -321,7 +321,7 @@ def close(self) -> None: """ self.plotter.close() - def export(self, savepath: str | Path, **kwargs: object) -> str: + def export(self, savepath: str | Path, **kwargs: Any) -> str: """ Export the scene to a ``.html`` file for online rendering. @@ -378,7 +378,7 @@ def screenshot( self, name: str | None = None, scale: float | None = None, - **kwargs: object, + **kwargs: Any, ) -> str: """ Take a screenshot of the current view and save it to file. From 99ff69ba6d66e143439bbb1f6c6c070786fcb82b Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 22 Jun 2026 16:28:03 +0000 Subject: [PATCH 5/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- brainrender/render.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/brainrender/render.py b/brainrender/render.py index 4125f90c..5f5508ea 100644 --- a/brainrender/render.py +++ b/brainrender/render.py @@ -4,9 +4,6 @@ from datetime import datetime from pathlib import Path - -from __future__ import annotations - from typing import TYPE_CHECKING, Any import numpy as np From 9cdcc90802efba31b6b1471547fac768ada08618 Mon Sep 17 00:00:00 2001 From: AlgoFoe Date: Mon, 22 Jun 2026 22:05:41 +0530 Subject: [PATCH 6/6] replace :meth: roles with inline code in docstrings --- brainrender/render.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/brainrender/render.py b/brainrender/render.py index 4125f90c..f440e28e 100644 --- a/brainrender/render.py +++ b/brainrender/render.py @@ -333,7 +333,7 @@ def export(self, savepath: str | Path, **kwargs: Any) -> str: savepath Path to the output ``.html`` file. **kwargs - Additional arguments forwarded to :meth:`render`. + Additional arguments forwarded to ``render``. Returns ------- @@ -397,7 +397,7 @@ def screenshot( Resolution multiplier. Values above 1 increase resolution. Falls back to ``settings.SCREENSHOT_SCALE`` if None. **kwargs - Additional arguments forwarded to :meth:`render`. + Additional arguments forwarded to ``render``. Returns -------