swcgeom 0.17.0__py3-none-any.whl → 0.17.2__py3-none-any.whl

swcgeom/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.17.0'
-__version_tuple__ = version_tuple = (0, 17, 0)
+__version__ = version = '0.17.2'
+__version_tuple__ = version_tuple = (0, 17, 2)

swcgeom/analysis/feature_extractor.py

@@ -7,10 +7,11 @@ naming specification.
 """
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from functools import cached_property
 from itertools import chain
 from os.path import basename
-from typing import Any, Callable, Dict, List, Literal, Tuple, overload
+from typing import Any, Literal, overload
 
 import numpy as np
 import numpy.typing as npt
@@ -18,8 +19,8 @@ import seaborn as sns
 from matplotlib.axes import Axes
 
 from swcgeom.analysis.features import (
-    BifurcationFeatures,
     BranchFeatures,
+    FurcationFeatures,
     NodeFeatures,
     PathFeatures,
     TipFeatures,
@@ -39,6 +40,9 @@ Feature = Literal[
     "node_count",
     "node_radial_distance",
     "node_branch_order",
+    # furcation nodes
+    "furcation_count",
+    "furcation_radial_distance",
     # bifurcation nodes
     "bifurcation_count",
     "bifurcation_radial_distance",
@@ -54,9 +58,9 @@ Feature = Literal[
 ]
 
 NDArrayf32 = npt.NDArray[np.float32]
-FeatAndKwargs = Feature | Tuple[Feature, Dict[str, Any]]
+FeatAndKwargs = Feature | tuple[Feature, dict[str, Any]]
 
-Feature1D = set(["length", "volume", "node_count", "bifurcation_count", "tip_count"])
+Feature1D = set(["length", "volume", "node_count", "furcation_count", "tip_count"])
 
 
 class Features:
@@ -69,7 +73,7 @@ class Features:
     @cached_property
     def node_features(self) -> NodeFeatures: return NodeFeatures(self.tree)
     @cached_property
-    def bifurcation_features(self) -> BifurcationFeatures: return BifurcationFeatures(self.node_features)
+    def furcation_features(self) -> FurcationFeatures: return FurcationFeatures(self.node_features)
     @cached_property
     def tip_features(self) -> TipFeatures: return TipFeatures(self.node_features)
     @cached_property
@@ -121,9 +125,9 @@ class FeatureExtractor(ABC):
     @overload
     def get(self, feature: Feature, **kwargs) -> NDArrayf32: ...
     @overload
-    def get(self, feature: List[FeatAndKwargs]) -> List[NDArrayf32]: ...
+    def get(self, feature: list[FeatAndKwargs]) -> list[NDArrayf32]: ...
     @overload
-    def get(self, feature: Dict[Feature, Dict[str, Any]]) -> Dict[str, NDArrayf32]: ...
+    def get(self, feature: dict[Feature, dict[str, Any]]) -> dict[str, NDArrayf32]: ...
     # fmt:on
     def get(self, feature, **kwargs):
         """Get feature.
@@ -168,7 +172,7 @@ class FeatureExtractor(ABC):
 
     # Custom Plots
 
-    def plot_node_branch_order(self, feature_kwargs: Dict[str, Any], **kwargs) -> Axes:
+    def plot_node_branch_order(self, feature_kwargs: dict[str, Any], **kwargs) -> Axes:
         vals = self._get("node_branch_order", **feature_kwargs)
         bin_edges = np.arange(int(np.ceil(vals.max() + 1))) + 0.5
         return self._plot_histogram_impl(vals, bin_edges, **kwargs)
@@ -213,6 +217,12 @@ class FeatureExtractor(ABC):
     ) -> Axes:
         raise NotImplementedError()
 
+    def get_bifurcation_count(self, **kwargs):
+        raise DeprecationWarning("Use `furcation_count` instead.")
+
+    def get_bifurcation_radial_distance(self, **kwargs):
+        raise DeprecationWarning("Use `furcation_radial_distance` instead.")
+
 
 class TreeFeatureExtractor(FeatureExtractor):
     """Extract feature from tree."""
@@ -234,7 +244,7 @@ class TreeFeatureExtractor(FeatureExtractor):
 
     def plot_sholl(
         self,
-        feature_kwargs: Dict[str, Any],  # pylint: disable=unused-argument
+        feature_kwargs: dict[str, Any],  # pylint: disable=unused-argument
         **kwargs,
     ) -> Axes:
         _, ax = self._features.sholl.plot(**kwargs)
@@ -264,7 +274,7 @@ class PopulationFeatureExtractor(FeatureExtractor):
     """Extract features from population."""
 
     _population: Population
-    _features: List[Features]
+    _features: list[Features]
 
     def __init__(self, population: Population) -> None:
         super().__init__()
@@ -279,7 +289,7 @@ class PopulationFeatureExtractor(FeatureExtractor):
 
     # Custom Plots
 
-    def plot_sholl(self, feature_kwargs: Dict[str, Any], **kwargs) -> Axes:
+    def plot_sholl(self, feature_kwargs: dict[str, Any], **kwargs) -> Axes:
         vals, rs = self._get_sholl_impl(**feature_kwargs)
         ax = self._lineplot(xs=rs, ys=vals.flatten(), **kwargs)
         ax.set_ylabel("Count of Intersections")
@@ -295,7 +305,7 @@ class PopulationFeatureExtractor(FeatureExtractor):
 
     def _get_sholl_impl(
         self, steps: int = 20, **kwargs
-    ) -> Tuple[NDArrayf32, NDArrayf32]:
+    ) -> tuple[NDArrayf32, NDArrayf32]:
         rmax = max(t.sholl.rmax for t in self._features)
         rs = Sholl.get_rs(rmax=rmax, steps=steps)
         vals = self._get_impl("sholl", steps=rs, **kwargs)
@@ -333,7 +343,7 @@ class PopulationsFeatureExtractor(FeatureExtractor):
     """Extract feature from population."""
 
     _populations: Populations
-    _features: List[List[Features]]
+    _features: list[list[Features]]
 
     def __init__(self, populations: Populations) -> None:
         super().__init__()
@@ -348,7 +358,7 @@ class PopulationsFeatureExtractor(FeatureExtractor):
 
     # Custom Plots
 
-    def plot_sholl(self, feature_kwargs: Dict[str, Any], **kwargs) -> Axes:
+    def plot_sholl(self, feature_kwargs: dict[str, Any], **kwargs) -> Axes:
         vals, rs = self._get_sholl_impl(**feature_kwargs)
         ax = self._lineplot(xs=rs, ys=vals, **kwargs)
         ax.set_ylabel("Count of Intersections")
@@ -369,7 +379,7 @@ class PopulationsFeatureExtractor(FeatureExtractor):
 
     def _get_sholl_impl(
         self, steps: int = 20, **kwargs
-    ) -> Tuple[NDArrayf32, NDArrayf32]:
+    ) -> tuple[NDArrayf32, NDArrayf32]:
         rmaxs = chain.from_iterable((t.sholl.rmax for t in p) for p in self._features)
         rmax = max(rmaxs)
         rs = Sholl.get_rs(rmax=rmax, steps=steps)

swcgeom/analysis/features.py

@@ -2,11 +2,11 @@
 
 from abc import ABC, abstractmethod
 from functools import cached_property
-from typing import List, TypeVar
+from typing import TypeVar
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 from swcgeom.core import Branch, BranchTree, Tree
 
@@ -121,12 +121,24 @@ class _SubsetNodesFeatures(ABC):
         return cls(NodeFeatures(tree))
 
 
-class BifurcationFeatures(_SubsetNodesFeatures):
-    """Evaluate bifurcation node feature of tree."""
+class FurcationFeatures(_SubsetNodesFeatures):
+    """Evaluate furcation node feature of tree."""
 
     @cached_property
     def nodes(self) -> npt.NDArray[np.bool_]:
-        return np.array([n.is_bifurcation() for n in self._features.tree])
+        return np.array([n.is_furcation() for n in self._features.tree])
+
+
+@deprecated("Use FurcationFeatures instead")
+class BifurcationFeatures(FurcationFeatures):
+    """Evaluate bifurcation node feature of tree.
+
+    Notes
+    -----
+    Deprecated due to the wrong spelling of furcation. For now, it
+    is just an alias of `FurcationFeatures` and raise a warning. It
+    will be change to raise an error in the future.
+    """
 
 
 class TipFeatures(_SubsetNodesFeatures):
@@ -163,7 +175,7 @@ class PathFeatures:
         return np.array([path.tortuosity() for path in self._paths], dtype=np.float32)
 
     @cached_property
-    def _paths(self) -> List[Tree.Path]:
+    def _paths(self) -> list[Tree.Path]:
         return self.tree.get_paths()
 
 
@@ -201,7 +213,7 @@ class BranchFeatures:
         return self.calc_angle(self._branches, eps=eps)
 
     @staticmethod
-    def calc_angle(branches: List[T], eps: float = 1e-7) -> npt.NDArray[np.float32]:
+    def calc_angle(branches: list[T], eps: float = 1e-7) -> npt.NDArray[np.float32]:
         """Calc agnle between branches.
 
         Returns
@@ -219,5 +231,5 @@ class BranchFeatures:
         return angle
 
     @cached_property
-    def _branches(self) -> List[Tree.Branch]:
+    def _branches(self) -> list[Tree.Branch]:
         return self.tree.get_branches()

swcgeom/analysis/lmeasure.py

@@ -1,13 +1,11 @@
 """L-Measure analysis."""
 
 import math
-from typing import Literal, Tuple
+from typing import Literal
 
 import numpy as np
 import numpy.typing as npt
-
 from swcgeom.core import Branch, Compartment, Node, Tree
-from swcgeom.utils import angle
 
 __all__ = ["LMeasure"]
 
@@ -69,7 +67,7 @@ class LMeasure:
         --------
         L-Measure: http://cng.gmu.edu:8080/Lm/help/N_bifs.htm
         """
-        return len(tree.get_bifurcations())
+        return len(tree.get_furcations())
 
     def n_branch(self, tree: Tree) -> int:
         """Number of branches.
@@ -163,12 +161,15 @@ class LMeasure:
         --------
         L-Measure: http://cng.gmu.edu:8080/Lm/help/Partition_asymmetry.htm
         """
+
         children = n.children()
         assert (
             len(children) == 2
         ), "Partition asymmetry is only defined for bifurcations"
         n1 = len(children[0].subtree().get_tips())
         n2 = len(children[1].subtree().get_tips())
+        if n1 == n2:
+            return 0
         return abs(n1 - n2) / (n1 + n2 - 2)
 
     def fractal_dim(self):
@@ -274,7 +275,7 @@ class LMeasure:
         rall_power, _, _, _ = self._rall_power(bif)
         return rall_power
 
-    def _rall_power_d(self, bif: Tree.Node) -> Tuple[float, float, float]:
+    def _rall_power_d(self, bif: Tree.Node) -> tuple[float, float, float]:
         children = bif.children()
         assert len(children) == 2, "Rall Power is only defined for bifurcations"
         parent = bif.parent()
@@ -284,7 +285,7 @@ class LMeasure:
         da, db = 2 * children[0].r, 2 * children[1].r
         return dp, da, db
 
-    def _rall_power(self, bif: Tree.Node) -> Tuple[float, float, float, float]:
+    def _rall_power(self, bif: Tree.Node) -> tuple[float, float, float, float]:
         dp, da, db = self._rall_power_d(bif)
         start, stop, step = 0, 5, 5 / 1000
         xs = np.arange(start, stop, step)
@@ -336,7 +337,7 @@ class LMeasure:
         return (da**rall_power + db**rall_power) / dp**rall_power
 
     def bif_ampl_local(self, bif: Tree.Node) -> float:
-        """Bifuraction angle.
+        """Bifurcation angle.
 
         Given a bifurcation, this function returns the angle between
         the first two compartments (in degree).
@@ -350,7 +351,7 @@ class LMeasure:
         return np.degrees(angle(v1, v2))
 
     def bif_ampl_remote(self, bif: Tree.Node) -> float:
-        """Bifuraction angle.
+        """Bifurcation angle.
 
         This function returns the angle between two bifurcation points
         or between bifurcation point and terminal point or between two
@@ -361,7 +362,7 @@ class LMeasure:
         L-Measure: http://cng.gmu.edu:8080/Lm/help/Bif_ampl_remote.htm
         """
 
-        v1, v2 = self._bif_vector_local(bif)
+        v1, v2 = self._bif_vector_remote(bif)
         return np.degrees(angle(v1, v2))
 
     def bif_tilt_local(self, bif: Tree.Node) -> float:
@@ -501,7 +502,7 @@ class LMeasure:
 
     def _bif_vector_local(
         self, bif: Tree.Node
-    ) -> Tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
+    ) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
         children = bif.children()
         assert len(children) == 2, "Only defined for bifurcations"
 
@@ -511,7 +512,7 @@ class LMeasure:
 
     def _bif_vector_remote(
         self, bif: Tree.Node
-    ) -> Tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
+    ) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
         children = bif.children()
         assert len(children) == 2, "Only defined for bifurcations"
 
@@ -665,7 +666,7 @@ class LMeasure:
         n = node
         order = 0
         while n is not None:
-            if n.is_bifurcation():
+            if n.is_furcation():
                 order += 1
             n = n.parent()
         return order
@@ -819,3 +820,23 @@ def pill_surface_area(ra: float, rb: float, h: float) -> float:
     bottom_hemisphere_area = 2 * math.pi * rb**2
     total_area = lateral_area + top_hemisphere_area + bottom_hemisphere_area
     return total_area
+
+
+# TODO: move to `utils`
+def angle(a: npt.ArrayLike, b: npt.ArrayLike) -> float:
+    """Get the angle of vectors.
+
+    Returns
+    -------
+    angle : float
+        Angle [0, PI) in radians.
+    """
+
+    a, b = np.array(a), np.array(b)
+    if np.linalg.norm(a) == 0 or np.linalg.norm(b) == 0:
+        raise ValueError("Input vectors must not be zero vectors.")
+
+    costheta = np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
+    costheta = np.clip(costheta, -1, 1)  # avoid numerical errors
+    theta = np.arccos(costheta)
+    return theta

swcgeom/analysis/sholl.py

@@ -1,13 +1,14 @@
 """Sholl analysis."""
 
 import warnings
-from typing import List, Literal, Optional, Tuple
+from typing import Literal, Optional
 
 import numpy as np
 import numpy.typing as npt
 import seaborn as sns
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
+from typing_extensions import deprecated
 
 from swcgeom.analysis.visualization import draw
 from swcgeom.core import Tree
@@ -84,18 +85,18 @@ class Sholl:
 
     def plot(  # pylint: disable=too-many-arguments
         self,
-        steps: List[float] | int = 20,
+        steps: list[float] | int = 20,
         plot_type: str | None = None,
         kind: Literal["bar", "linechart", "circles"] = "circles",
         fig: Figure | None = None,
         ax: Axes | None = None,
         **kwargs,
-    ) -> Tuple[Figure, Axes]:
+    ) -> tuple[Figure, Axes]:
         """Plot Sholl analysis.
 
         Parameters
         ----------
-        steps : int or List[float], default to 20
+        steps : int or list[float], default to 20
             Steps of raius of circle. If steps is int, then it will be
             evenly divided into n radii.
         kind : "bar" | "linechart" | "circles", default `circles`
@@ -160,20 +161,17 @@ class Sholl:
 
         return self.get_rs(self.rmax, steps)
 
+    @deprecated("Use `Sholl.get(x)` instead")
     def get_count(self) -> npt.NDArray[np.int32]:
         """Get the count of intersection.
 
         .. deprecated:: 0.5.0
-            Use :meth:`Sholl.get` instead.
+            Use :meth:`Sholl(x).get()` instead.
         """
 
-        warnings.warn(
-            "`Sholl.get_count` has been renamed to `get` since v0.5.0, "
-            "and will be removed in next version",
-            DeprecationWarning,
-        )
         return self.get().astype(np.int32)
 
+    @deprecated("Use `Shool(x).get().mean()` instead")
     def avg(self) -> float:
         """Get the average of the count of intersection.
 
@@ -181,14 +179,9 @@ class Sholl:
             Use :meth:`Shool(x).get().mean()` instead.
         """
 
-        warnings.warn(
-            "`Sholl.avg` has been deprecated since v0.6.0 and will be "
-            "removed in next version, use `Shool(x).get().mean()` "
-            "instead",
-            DeprecationWarning,
-        )
         return self.get().mean()
 
+    @deprecated("Use `Shool(x).get().std()` instead")
     def std(self) -> float:
         """Get the std of the count of intersection.
 
@@ -196,14 +189,9 @@ class Sholl:
             Use :meth:`Shool(x).get().std()` instead.
         """
 
-        warnings.warn(
-            "`Sholl.std` has been deprecate since v0.6.0 and will be "
-            "removed in next version, use `Shool(x).get().std()` "
-            "instead",
-            DeprecationWarning,
-        )
         return self.get().std()
 
+    @deprecated("Use `Shool(x).get().sum()` instead")
     def sum(self) -> int:
         """Get the sum of the count of intersection.
 
@@ -211,10 +199,4 @@ class Sholl:
             Use :meth:`Shool(x).get().sum()` instead.
         """
 
-        warnings.warn(
-            "`Sholl.sum` has been deprecate since v0.6.0 and will be "
-            "removed in next version, use `Shool(x).get().sum()` "
-            "instead",
-            DeprecationWarning,
-        )
         return self.get().sum()

swcgeom/analysis/trunk.py

@@ -2,8 +2,9 @@
 
 # pylint: disable=invalid-name
 
+from collections.abc import Iterable
 from itertools import chain
-from typing import Any, Dict, Iterable, List, Literal, Optional, Tuple, cast
+from typing import Any, Literal, Optional, cast
 
 import numpy as np
 import numpy.typing as npt
@@ -28,28 +29,28 @@ def draw_trunk(
     *,
     fig: Optional[Figure] = None,
     ax: Optional[Axes] = None,
-    bound: Bounds | Tuple[Bounds, Dict[str, Any]] | None = "ellipse",
-    point: bool | Dict[str, Any] = True,
+    bound: Bounds | tuple[Bounds, dict[str, Any]] | None = "ellipse",
+    point: bool | dict[str, Any] = True,
     projection: Projection = "2d",
     cmap: Any = "viridis",
     **kwargs,
-) -> Tuple[Figure, Axes]:
+) -> tuple[Figure, Axes]:
     """Draw trunk tree.
 
     Parameters
     ----------
     t : Tree
-    florets : List of (int | List of int)
+    florets : List of (int | list of int)
         The florets that needs to be removed, each floret can be a
         subtree or multiple subtrees (e.g., dendrites are a bunch of
         subtrees), each number is the id of a tree node.
     fig : ~matplotlib.figure.Figure, optional
     ax : ~matplotlib.axes.Axes, optional
-    bound : Bounds | (Bounds, Dict[str, Any]) | None, default 'ellipse'
+    bound : Bounds | (Bounds, dict[str, Any]) | None, default 'ellipse'
         Kind of bound, support 'aabb', 'ellipse'. If bound is None, no
         bound will be drawn. If bound is a tuple, the second item will
         used as kwargs and forward to draw function.
-    point : bool | Dict[str, Any], default True
+    point : bool | dict[str, Any], default True
         Draw point at the start of a subtree. If point is False, no
         point will be drawn. If point is a dict, this will used a
         kwargs and forward to draw function.
@@ -57,7 +58,7 @@ def draw_trunk(
         Colormap, any value supported by ~matplotlib.cm.Colormap. We
         will use the ratio of the length of the subtree to the total
         length of the tree to determine the color.
-    **kwargs : Dict[str, Any]
+    **kwargs : dict[str, Any]
         Forward to ~swcgeom.analysis.draw.
     """
     # pylint: disable=too-many-locals
@@ -83,14 +84,14 @@ def draw_trunk(
 
 def split_florets(
     t: Tree, florets: Iterable[int | Iterable[int]]
-) -> Tuple[Tree, List[List[Tree]]]:
+) -> tuple[Tree, list[list[Tree]]]:
     florets = [[i] if isinstance(i, (int, np.integer)) else i for i in florets]
     subtrees = [[get_subtree(t, ff) for ff in f] for f in florets]
     trunk = to_subtree(t, chain(*florets))
     return trunk, subtrees
 
 
-def get_length_ratio(t: Tree, tss: List[List[Tree]]) -> Any:
+def get_length_ratio(t: Tree, tss: list[list[Tree]]) -> Any:
     lens = np.array([sum(t.length() for t in ts) for ts in tss])
     return lens / t.length()
 
@@ -101,7 +102,7 @@ def get_length_ratio(t: Tree, tss: List[List[Tree]]) -> Any:
 def draw_bound(
     ts: Iterable[Tree],
     ax: Axes,
-    bound: Bounds | Tuple[Bounds, Dict[str, Any]],
+    bound: Bounds | tuple[Bounds, dict[str, Any]],
     projection: Projection,
     **kwargs,
 ) -> None:

swcgeom/analysis/visualization.py

@@ -2,7 +2,7 @@
 
 import os
 import weakref
-from typing import Any, Dict, List, Literal, Optional, Tuple
+from typing import Any, Literal, Optional
 
 import numpy as np
 from matplotlib.axes import Axes
@@ -21,15 +21,15 @@ from swcgeom.utils import (
 
 __all__ = ["draw"]
 
-Positions = Literal["lt", "lb", "rt", "rb"] | Tuple[float, float]
-locations: Dict[Literal["lt", "lb", "rt", "rb"], Tuple[float, float]] = {
+Positions = Literal["lt", "lb", "rt", "rb"] | tuple[float, float]
+locations: dict[Literal["lt", "lb", "rt", "rb"], tuple[float, float]] = {
     "lt": (0.10, 0.90),
     "lb": (0.10, 0.10),
     "rt": (0.90, 0.90),
     "rb": (0.90, 0.10),
 }
 
-ax_weak_memo = weakref.WeakKeyDictionary[Axes, Dict[str, Any]]({})
+ax_weak_memo = weakref.WeakKeyDictionary[Axes, dict[str, Any]]({})
 
 
 def draw(
@@ -39,7 +39,7 @@ def draw(
     ax: Optional[Axes] = None,
     show: bool | None = None,
     camera: CameraOptions = "xy",
-    color: Optional[Dict[int, str] | str] = None,
+    color: Optional[dict[int, str] | str] = None,
     label: str | bool = True,
     direction_indicator: Positions | Literal[False] = "rb",
     unit: Optional[str] = None,
@@ -64,7 +64,7 @@ def draw(
         vector, then then threat it as (look-at, up), so camera is
         ((0, 0, 0), look-at, up). An easy way is to use the presets
         "xy", "yz" and "zx".
-    color : Dict[int, str] | "vaa3d" | str, optional
+    color : dict[int, str] | "vaa3d" | str, optional
         Color map. If is dict, segments will be colored by the type of
         parent node.If is string, the value will be use for any type.
     label : str | bool, default True
@@ -120,14 +120,14 @@ def draw(
     return fig, ax
 
 
-def get_ax_swc(ax: Axes) -> List[SWCLike]:
+def get_ax_swc(ax: Axes) -> list[SWCLike]:
     ax_weak_memo.setdefault(ax, {})
     return ax_weak_memo[ax]["swc"]
 
 
 def get_ax_color(
-    ax: Axes, swc: SWCLike, color: Optional[Dict[int, str] | str] = None
-) -> str | List[str]:
+    ax: Axes, swc: SWCLike, color: Optional[dict[int, str] | str] = None
+) -> str | list[str]:
     if color == "vaa3d":
         color = palette.vaa3d
     elif isinstance(color, str):

swcgeom/analysis/visualization3d.py

@@ -0,0 +1,85 @@
+"""Painter utils.
+
+Notes
+-----
+This is a experimental function, it may be changed in the future.
+"""
+
+from typing import Optional
+
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from mpl_toolkits.mplot3d import Axes3D
+
+from swcgeom.analysis.visualization import (
+    _set_ax_memo,
+    get_ax_color,
+    get_ax_swc,
+    set_ax_legend,
+)
+from swcgeom.core import SWCLike, Tree
+from swcgeom.utils.plotter_3d import draw_lines_3d
+
+__all__ = ["draw3d"]
+
+
+# TODO: support Camera
+def draw3d(
+    swc: SWCLike | str,
+    *,
+    ax: Axes,
+    show: bool | None = None,
+    color: Optional[dict[int, str] | str] = None,
+    label: str | bool = True,
+    **kwargs,
+) -> tuple[Figure, Axes]:
+    r"""Draw neuron tree.
+
+    Parameters
+    ----------
+    swc : SWCLike | str
+        If it is str, then it is treated as the path of swc file.
+    fig : ~matplotlib.axes.Figure, optional
+    ax : ~matplotlib.axes.Axes, optional
+    show : bool | None, default `None`
+        Wheather to call `plt.show()`. If not specified, it will depend
+        on if ax is passed in, it will not be called, otherwise it will
+        be called by default.
+    color : dict[int, str] | "vaa3d" | str, optional
+        Color map. If is dict, segments will be colored by the type of
+        parent node.If is string, the value will be use for any type.
+    label : str | bool, default True
+        Label of legend, disable if False.
+    **kwargs : dict[str, Unknown]
+        Forwarded to `~mpl_toolkits.mplot3d.art3d.Line3DCollection`.
+    """
+
+    assert isinstance(ax, Axes3D), "only support 3D axes."
+
+    swc = Tree.from_swc(swc) if isinstance(swc, str) else swc
+
+    show = (show is True) or (show is None and ax is None)
+    my_color = get_ax_color(ax, swc, color)  # type: ignore
+
+    xyz = swc.xyz()
+    starts, ends = swc.id()[1:], swc.pid()[1:]
+    lines = np.stack([xyz[starts], xyz[ends]], axis=1)
+    collection = draw_lines_3d(ax, lines, color=my_color, **kwargs)
+
+    min_vals = lines.reshape(-1, 3).min(axis=0)
+    max_vals = lines.reshape(-1, 3).max(axis=0)
+    ax.set_xlim(min_vals[0], max_vals[0])
+    ax.set_ylim(min_vals[1], max_vals[1])
+    ax.set_zlim(min_vals[2], max_vals[2])
+
+    _set_ax_memo(ax, swc, label=label, handle=collection)
+
+    if len(get_ax_swc(ax)) == 1:
+        # ax.set_aspect(1)
+        ax.spines[["top", "right"]].set_visible(False)
+    else:
+        set_ax_legend(ax, loc="upper right")  # enable legend
+
+    fig = ax.figure
+    return fig, ax  # type: ignore