vuer 0.0.16__py3-none-any.whl → 0.0.18__py3-none-any.whl

vuer/events.py

@@ -1,7 +1,8 @@
-from typing import List, Type
+from typing import List, Tuple
 from uuid import uuid4
 
-from vuer.schemas import Element, Scene
+from vuer.schemas import Scene
+from vuer.schemas import Element
 from vuer.serdes import serializer
 
 
@@ -124,7 +125,7 @@ class Update(ServerEvent):
 
     etype = "UPDATE"
 
-    def __init__(self, *elements: List[Element], strict=False):
+    def __init__(self, *elements: Element, strict=False):
         # tuple is not serializable
         super().__init__({"nodes": elements}, strict=strict)
 

vuer/schemas/__init__.py

@@ -0,0 +1,3 @@
+from .html_components import *
+from .scene_components import *
+from .drei_components import *

vuer/schemas/drei_components.py

@@ -0,0 +1,171 @@
+from vuer.schemas.scene_components import SceneElement
+
+
+class Html(SceneElement):
+    tag = "Html"
+
+
+class Splat(SceneElement):
+    tag = "Splat"
+
+
+class Line(SceneElement):
+    """
+    Renders a THREE.Line2 or THREE.LineSegments2 (depending on the value of segments).
+
+    Usage::
+
+        <Line
+          points={[[0, 0, 0], ...]}       // Array of points, Array<Vector3 | Vector2 | [number, number, number] | [number, number] | number>
+          color="black"                   // Default
+          lineWidth={1}                   // In pixels (default)
+          segments                        // If true, renders a THREE.LineSegments2. Otherwise, renders a THREE.Line2
+          dashed={false}                  // Default
+          vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
+          {...lineProps}                  // All THREE.Line2 props are valid
+          {...materialProps}              // All THREE.LineMaterial props are valid
+        />
+    """
+
+    tag = "Line"
+
+
+class QuadraticBezierLine(SceneElement):
+    """
+
+    Renders a THREE.Line2 using THREE.QuadraticBezierCurve3 for interpolation.
+
+    Usage::
+
+        <QuadraticBezierLine
+          start={[0, 0, 0]}               // Starting point, can be an array or a vec3
+          end={[10, 0, 10]}               // Ending point, can be an array or a vec3
+          mid={[5, 0, 5]}                 // Optional control point, can be an array or a vec3
+          color="black"                   // Default
+          lineWidth={1}                   // In pixels (default)
+          dashed={false}                  // Default
+          vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
+          {...lineProps}                  // All THREE.Line2 props are valid
+          {...materialProps}              // All THREE.LineMaterial props are valid
+        />
+
+    You can also update the line runtime.
+
+    code::
+
+        const ref = useRef()
+        useFrame((state) => {
+          ref.current.setPoints(
+            [0, 0, 0],
+            [10, 0, 0],
+            // [5, 0, 0] // Optional: mid-point
+          )
+        }, [])
+        return <QuadraticBezierLine ref={ref} />
+        }
+    """
+
+    tag = "QuadraticBezierLine"
+
+
+class CubicBezierLine(SceneElement):
+    """
+    Renders a THREE.Line2 using THREE.CubicBezierCurve3 for interpolation.
+
+    Usage::
+
+        <CubicBezierLine
+          start={[0, 0, 0]}               // Starting point
+          end={[10, 0, 10]}               // Ending point
+          midA={[5, 0, 0]}                // First control point
+          midB={[0, 0, 5]}                // Second control point
+          color="black"                   // Default
+          lineWidth={1}                   // In pixels (default)
+          dashed={false}                  // Default
+          vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
+          {...lineProps}                  // All THREE.Line2 props are valid
+          {...materialProps}              // All THREE.LineMaterial props are valid
+        />
+    """
+
+    tag = "CubicBezierLine"
+
+
+class CatmullRomLine(SceneElement):
+    """
+    Renders a THREE.Line2 using THREE.CatmullRomCurve3 for interpolation.
+
+    Usage::
+
+        <CatmullRomLine
+          points={[[0, 0, 0], ...]}       // Array of Points
+          closed={false}                  // Default
+          curveType="centripetal"         // One of "centripetal" (default), "chordal", or "catmullrom"
+          tension={0.5}                   // Default (only applies to "catmullrom" curveType)
+          color="black"                   // Default
+          lineWidth={1}                   // In pixels (default)
+          dashed={false}                  // Default
+          vertexColors={[[0, 0, 0], ...]} // Optional array of RGB values for each point
+          {...lineProps}                  // All THREE.Line2 props are valid
+          {...materialProps}              // All THREE.LineMaterial props are valid
+        />
+    """
+
+    tag = "CatmullRomLine"
+
+
+class Facemesh(SceneElement):
+    """Renders an oriented MediaPipe face mesh:
+
+    :param points: An array of 468+ keypoints as returned by google/mediapipe tasks-vision. Defaults to a sample face.
+    :type  points: MediaPipePoints, optional
+    :param face: An face object as returned by tensorflow/tfjs-models face-landmarks-detection. This parameter is deprecated.
+    :type  face: MediaPipeFaceMesh, optional
+    :param width: Constant width of the mesh. Defaults to undefined.
+    :type  width: int, optional
+    :param height: Constant height of the mesh. Defaults to undefined.
+    :type  height: int, optional
+    :param depth: Constant depth of the mesh. Defaults to 1.
+    :type  depth: int, optional
+    :param verticalTri: A landmarks tri supposed to be vertical. Defaults to [159, 386, 200]. See: https://github.com/tensorflow/tfjs-models/tree/master/face-landmarks-detection#mediapipe-facemesh-keypoints
+    :type  verticalTri: Tuple[int, int, int], optional
+    :param origin: A landmark index (to get the position from) or a vec3 to be the origin of the mesh. Defaults to undefined (i.e., the bbox center).
+    :type  origin: Union[int, THREE.Vector3], optional
+    :param facialTransformationMatrix: A facial transformation matrix, as returned by FaceLandmarkerResult.facialTransformationMatrixes. See: https://developers.google.com/mediapipe/solutions/vision/face_landmarker/web_js#handle_and_display_results
+    :type  facialTransformationMatrix: FacemeshDatas.SAMPLE_FACELANDMARKER_RESULT.facialTransformationMatrixes[0], optional
+    :param offset: Apply position offset extracted from `facialTransformationMatrix`.
+    :type  offset: bool, optional
+    :param offsetScalar: Offset sensitivity factor, less is more sensible.
+    :type  offsetScalar: float, optional
+    :param faceBlendshapes: Face blendshapes, as returned by FaceLandmarkerResult.faceBlendshapes. See: https://developers.google.com/mediapipe/solutions/vision/face_landmarker/web_js#handle_and_display_results
+    :type  faceBlendshapes: FacemeshDatas.SAMPLE_FACELANDMARKER_RESULT.faceBlendshapes[0], optional
+    :param eyes: Whether to enable eyes (note: `faceBlendshapes` is required for this). Defaults to True.
+    :type  eyes: bool, optional
+
+    Usage::
+
+        const faceLandmarkerResult = {
+            "faceLandmarks": [
+              [
+                { "x": 0.5760777592658997, "y": 0.8639070391654968, "z": -0.030997956171631813 },
+                { "x": 0.572094738483429, "y": 0.7886289358139038, "z": -0.07189624011516571 },
+                // ...
+              ],
+              // ...
+            ],
+            "faceBlendshapes": [
+              // ...
+            ],
+            "facialTransformationMatrixes": [
+              // ...
+            ]
+          },
+        }
+
+        const points = faceLandmarkerResult.faceLandmarks[0]
+
+        <Facemesh points={points} />
+
+    """
+
+    tag = "Facemesh"

vuer/schemas/html_components.py

@@ -0,0 +1,253 @@
+from typing import Union
+
+import numpy as np
+from PIL import Image as pil_image
+
+from vuer.serdes import IMAGE_FORMATS
+
+element_count = 0
+
+
+class Element:
+    """
+    Base class for all elements
+    """
+
+    tag: str = "div"
+
+    def __post_init__(self, **kwargs):
+        pass
+
+    def __init__(self, key=None, **kwargs):
+        global element_count
+        if key is None:
+            key = str(element_count)
+            element_count += 1
+
+        self.__dict__.update(tag=self.tag, key=key, **kwargs)
+        self.__post_init__(**{k: v for k, v in kwargs.items() if k.startswith("_")})
+
+    def serialize(self):
+        """
+        Serialize the element to a dictionary for sending over the websocket.
+
+        :return: Dictionary representing the element.
+        """
+
+        # note: only return the non-private attributes, allow bypass.
+        output = {}
+        for k, v in self.__dict__.items():
+            if k.startswith("_"):
+                continue
+            if hasattr(v, "tolist"):
+                output[k] = v.tolist()
+            else:
+                output[k] = v
+
+        return output
+
+
+class BlockElement(Element):
+    def __init__(self, *children, **kwargs):
+        self.children = children
+        super().__init__(**kwargs)
+
+    def serialize(self):
+        # writ this as multiple lines
+        children = []
+        for e in self.children:
+            if isinstance(e, str):
+                children.append(e)
+            else:
+                children.append(e.serialize())
+        return {**super().serialize(), "children": children}
+
+
+class AutoScroll(BlockElement):
+    tag = "AutoScroll"
+
+
+class Markdown(BlockElement):
+    tag = "Markdown"
+
+
+class Page(BlockElement):
+    """
+    A Page is an element that contains other elements.
+    It is represented by a div element in the DOM.
+    """
+
+    tag = "article"
+
+
+class div(BlockElement):
+    tag = "Div"
+
+
+class InputBox(Element):
+    """
+    An InputBox is an element that allows the user to input text.
+    It is represented by an input element in the DOM.
+    """
+
+    tag = "Input"
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+
+class Header1(BlockElement):
+    """
+    A Text element is an element that displays text.
+    It is represented by a text, or p element in the DOM.
+    """
+
+    tag = "h1"
+
+    def __init__(self, *children, **kwargs):
+        children = [Text(c) if isinstance(c, str) else c for c in children]
+        super().__init__(*children, **kwargs)
+
+
+Header = Header1
+
+
+class Header2(Header1):
+    """Header 2"""
+
+    tag = "h2"
+
+
+class Header3(Header1):
+    """Header 2"""
+
+    tag = "h3"
+
+
+class Paragraph(BlockElement):
+    """
+    A Text element is an element that displays text.
+    It is represented by a text, or p element in the DOM.
+    """
+
+    tag = "p"
+
+    def __init__(self, *children, **kwargs):
+        children = [Text(c) if isinstance(c, str) else c for c in children]
+        super().__init__(*children, **kwargs)
+
+
+class Text(Element):
+    """
+    A Text element is an element that displays text.
+    It is represented by a text, or p element in the DOM.
+    """
+
+    tag = "Text"
+
+    def __init__(self, *text, sep=" ", **kwargs):
+        self.text = sep.join(text)
+        super().__init__(**kwargs)
+
+
+class Bold(Text):
+    def __init__(self, text, style=None, **kwargs):
+        _style = {"fontWeight": "bold"}
+        _style.update(style or {})
+        super().__init__(text, style=_style, **kwargs)
+
+
+class Italic(Text):
+    def __init__(self, text, style=None, **kwargs):
+        _style = {"fontStyle": "italic"}
+        _style.update(style or {})
+        super().__init__(text, style=_style, **kwargs)
+
+
+class Link(Text):
+    tag = "a"
+
+    def __init__(self, text, src, **kwargs):
+        super().__init__(text, src=src, **kwargs)
+
+
+class Button(Element):
+    """
+    A Button element is an element that allows the user to click on it.
+    It is represented by a button element in the DOM.
+    """
+
+    tag = "Button"
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+
+class Slider(Element):
+    """
+    A Slider element is an element that allows the user to slide a value.
+    It is represented by a slider element in the DOM.
+    """
+
+    tag = "Slider"
+
+    def __init__(self, **kwargs):
+        """
+        :param min: Minimum value of the slider
+        :param max: Maximum value of the slider
+        :param step: Step size of the slider
+        :param value: Initial value of the slider
+        :param kwargs:
+        """
+        super().__init__(**kwargs)
+
+
+class Image(Element):
+    """
+    An Image element is an element that displays an image.
+    It is represented by an img element in the DOM.
+    """
+
+    tag = "Img"
+
+    def __init__(
+        self,
+        data: Union[str, np.ndarray, pil_image.Image] = None,
+        *,
+        src: str = None,
+        format="png",
+        **kwargs,
+    ):
+        if src is not None:
+            assert data is None, "data and src can not be truful at the same time"
+        if data is None:
+            pass
+        elif isinstance(data, list) and len(data) == 0:
+            pass
+        else:
+            if isinstance(data, pil_image.Image):
+                data = data
+            elif isinstance(data, str):
+                # convert back to image first from base64
+                data = pil_image.open(data)
+            elif isinstance(data, np.ndarray):
+                if data.dtype == np.uint8:
+                    pass
+                else:
+                    data = (data * 255).astype(np.uint8)
+
+            src = IMAGE_FORMATS[format](data)
+
+        super().__init__(src=src, **kwargs)
+
+
+class ImageUpload(Element):
+    """
+    A ImageUpload element is an element that allows the user to upload a file.
+    It is represented by a file upload element in the DOM.
+    """
+
+    tag = "ImageUpload"
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)

vuer/schemas/scene_components.py

@@ -0,0 +1,522 @@
+import numpy as np
+from numpy._typing import NDArray
+from typing import List
+
+from vuer.schemas.html_components import BlockElement, Image, Element
+
+
+class Scene(BlockElement):
+    tag = "Scene"
+
+    def __init__(
+        self,
+        *children,
+        rawChildren=None,
+        htmlChildren=None,
+        bgChildren=None,
+        # default to y-up to be consistent with three.js. Blender uses z-up though.
+        up=[0, 1, 0],
+        **kwargs,
+    ):
+        super().__init__(*children, up=up, **kwargs)
+        self.rawChildren = rawChildren or []
+        self.htmlChildren = htmlChildren or []
+        self.bgChildren = bgChildren or []
+
+    def serialize(self):
+        obj = super().serialize()
+        if self.rawChildren:
+            obj["rawChildren"] = [e.serialize() for e in self.rawChildren if e]
+        if self.htmlChildren:
+            obj["htmlChildren"] = [e.serialize() for e in self.htmlChildren if e]
+        if self.bgChildren:
+            obj["bgChildren"] = [e.serialize() for e in self.bgChildren if e]
+        return obj
+
+
+class SceneElement(BlockElement):
+    pass
+
+
+class Frustum(SceneElement):
+    """Camera Frustum
+
+    :param position: An optional tuple of three numbers representing the position.
+    :type position: tuple[float, float, float]
+    :param rotation: An optional tuple of three numbers representing the rotation.
+    :type rotation: tuple[float, float, float]
+    :param matrix: An optional tuple of sixteen numbers representing the matrix.
+    :type matrix: tuple[float, float, float, float, float, float, float, float, float, float, float, float, float, float, float, float]
+    :param aspect: An optional number representing the aspect.
+    :type aspect: float
+    :param focus: An optional number representing the focus.
+    :type focus: float
+    :param fov: An optional number representing the field of view.
+    :type fov: float
+    :param near: An optional number representing the near field.
+    :type near: float
+    :param far: An optional number representing the far field.
+    :type far: float
+    :param scale: An optional number representing the scale.
+    :type scale: float
+    :param upScale: An optional number representing the up scale.
+    :type upScale: float
+    :param focalLength: An optional number representing the focal length.
+    :type focalLength: float
+    :param showUp: An optional boolean indicating whether to show up.
+    :type showUp: bool
+    :param showFrustum: An optional boolean indicating whether to show the frustum.
+    :type showFrustum: bool
+    :param showFocalPlane: An optional boolean indicating whether to show the focal plane.
+    :type showFocalPlane: bool
+    :param showImagePlane: An optional boolean indicating whether to show the image plane.
+    :type showImagePlane: bool
+    :param src: An optional string representing the source.
+    :type src: str
+    :param colorOrigin: An optional ColorRepresentation for the origin color.
+    :type colorOrigin: ColorRepresentation
+    :param colorFrustum: An optional ColorRepresentation for the frustum color.
+    :type colorFrustum: ColorRepresentation
+    :param colorCone: An optional ColorRepresentation for the cone color.
+    :type colorCone: ColorRepresentation
+    :param colorFocalPlane: An optional ColorRepresentation for the focal plane color.
+    :type colorFocalPlane: ColorRepresentation
+    :param colorUp: An optional ColorRepresentation for the up color.
+    :type colorUp: ColorRepresentation
+    :param colorTarget: An optional ColorRepresentation for the target color.
+    :type colorTarget: ColorRepresentation
+    :param colorCross: An optional ColorRepresentation for the cross color.
+    :type colorCross: ColorRepresentation
+    """
+
+    tag = "Frustum"
+
+
+class CameraHelper(SceneElement):
+    tag = "CameraHelper"
+
+
+class group(SceneElement):
+    tag = "group"
+    children = []
+
+
+class mesh(SceneElement):
+    tag = "mesh"
+    children = []
+
+
+class TriMesh(SceneElement):
+    tag = "TriMesh"
+    children = []
+
+    vertices: NDArray[np.float16] = None
+    # note: Uint16 is too few. Quickly overflows
+    faces: NDArray[np.uint32] = None
+    colors: NDArray[np.uint8] = None
+
+    def __post_init__(self, **kwargs):
+        self.vertices = self.vertices.astype(np.float16).flatten().tobytes()
+
+        # uinit16 is too few at 65536. Have to use uint32.
+        self.faces = self.faces.astype(np.uint32).flatten().tobytes()
+
+        if self.colors is None:
+            return
+
+        if self.colors.shape[-1] == 4:
+            self.colors = self.colors[:, :3]
+
+        # send only integers: https://stackoverflow.com/questions/34669537
+        if self.colors.dtype != np.uint8:
+            self.colors *= 255
+            self.colors = self.colors.astype(np.uint8)
+
+        self.colors = self.colors.flatten().tobytes()
+
+
+class PointCloud(SceneElement):
+    """PointCould element, highly optimized for payload size and speed.
+
+    :param vertices: An optional numpy array of shape (N, 3) containing the vertices of the pointcloud.
+    :type  vertices: NDArray[np.float16]
+    :param colors: An optional numpy array of shape (N, 3) containing the colors of the point cloud.
+    :type  color: NDArray[np.uint8]
+    :param size: An optional float that sets the size of the points.
+    :type  size: float
+    :param key: str An optional string that sets the key of the element.
+    :type  key: str
+
+    Usage::
+
+        sess.upsert @ PointCloud(
+            vertices=np.random.rand(1000, 3),
+            colors=np.random.rand(1000, 3),
+            size=0.01,
+            key="pointcloud",
+        )
+
+    """
+
+    tag: str = "PointCloud"
+    vertices: NDArray[np.float16] = None
+    """An optional numpy array of shape (N, 3) containing the vertices of the point cloud."""
+    colors: NDArray[np.uint8] = None
+    """An optional numpy array of shape (N, 3) containing the colors of the point cloud."""
+    children = []
+
+    def __post_init__(self, **kwargs):
+        self.vertices = self.vertices.astype(np.float16).flatten().tobytes()
+
+        if self.colors is None:
+            return
+
+        if self.colors.shape[-1] == 4:
+            self.colors = self.colors[:, :3]
+
+        if self.colors.dtype != np.uint8:
+            # todo: use this and send only integers: https://stackoverflow.com/questions/34669537
+            self.colors *= 255
+            self.colors = self.colors.astype(np.uint8)
+
+        self.colors = self.colors.flatten().tobytes()
+
+
+p = PointCloud
+
+
+class Box(SceneElement):
+    tag = "Box"
+
+
+class Capsule(SceneElement):
+    tag = "Capsule"
+
+
+class Cone(SceneElement):
+    tag = "Cone"
+
+
+class Circle(SceneElement):
+    tag = "Circle"
+
+
+class Cylinder(SceneElement):
+    tag = "Cylinder"
+
+
+class Dodecahedron(SceneElement):
+    tag = "Dodecahedron"
+
+
+class Edges(SceneElement):
+    tag = "Edges"
+
+
+class Extrude(SceneElement):
+    tag = "Extrude"
+
+
+class Icosahedron(SceneElement):
+    tag = "Icosahedron"
+
+
+class Lathe(SceneElement):
+    tag = "Lathe"
+
+
+class Octahedron(SceneElement):
+    tag = "Octahedron"
+
+
+class Plane(SceneElement):
+    tag = "Plane"
+
+
+class Polyhedron(SceneElement):
+    tag = "Polyhedron"
+
+
+class Ring(SceneElement):
+    tag = "Ring"
+
+
+class Shape(SceneElement):
+    tag = "Shape"
+
+
+class Sphere(SceneElement):
+    tag = "Sphere"
+
+
+class Tetrahedron(SceneElement):
+    tag = "Tetrahedron"
+
+
+class Torus(SceneElement):
+    tag = "Torus"
+
+
+class TorusKnot(SceneElement):
+    tag = "TorusKnot"
+
+
+class Tube(SceneElement):
+    tag = "Tube"
+
+
+class Fog(SceneElement):
+    """
+    Fog is a scene element that adds fog to the scene. This
+    can be used to approximate depth.
+
+    Arguments:
+        args: color, near, far
+
+    Example Usage:
+        Fog(args=[0xcccccc, 10, 15])
+
+    """
+
+    tag = "fog"
+
+
+class Wireframe(SceneElement):
+    tag = "Wireframe"
+
+
+class Splat(SceneElement):
+    tag = "Splat"
+
+
+class LumaSplats(SceneElement):
+    tag = "Splats"
+
+
+class Pcd(SceneElement):
+    tag = "Pcd"
+
+
+class CameraView(SceneElement):
+    tag = "CameraView"
+
+
+class SceneBackground(Image, SceneElement):
+    """Sets the background of the scene to a static image. Does not work well
+    with high frame rates. For displaying movies, use the ImageBackground element.
+    """
+
+    tag = "SceneBackground"
+
+
+class ImageBackground(Image, SceneElement):
+    """Sets the background of the scene to an image, Supports high frame rates.
+
+    We use a plane that is always facing the camera to display the image.
+    """
+
+    tag = "ImageBackground"
+
+
+class Gamepads(SceneElement):
+    tag = "Gamepads"
+
+
+class DirectionalLight(SceneElement):
+    tag = "DirectionalLight"
+
+
+class PointLight(SceneElement):
+    tag = "PointLight"
+
+
+class SpotLight(SceneElement):
+    tag = "SpotLight"
+
+
+class AmbientLight(SceneElement):
+    tag = "AmbientLight"
+
+
+class Html(SceneElement):
+    """
+    Usage::
+
+        as='div' // Wrapping element (default: 'div')
+        wrapperClass // The className of the wrapping element (default: undefined)
+        prepend // Project content behind the canvas (default: false)
+        center // Adds a -50%/-50% css transform (default: false) [ignored in transform mode]
+        fullscreen // Aligns to the upper-left corner, fills the screen (default:false) [ignored in transform mode]
+        distanceFactor={10} // If set (default: undefined), children will be scaled by this factor, and also by distance to a PerspectiveCamera / zoom by a OrthographicCamera.
+        zIndexRange={[100, 0]} // Z-order range (default=[16777271, 0])
+        portal={domnodeRef} // Reference to target container (default=undefined)
+        transform // If true, applies matrix3d transformations (default=false)
+        sprite // Renders as sprite, but only in transform mode (default=false)
+        calculatePosition={(el: Object3D, camera: Camera, size: { width: number; height: number }) => number[]} // Override default positioning function. (default=undefined) [ignored in transform mode]
+        occlude={[ref]} // Can be true or a Ref<Object3D>[], true occludes the entire scene (default: undefined)
+        onOcclude={(visible) => null} // Callback when the visibility changes (default: undefined)
+        {...groupProps} // All THREE.Group props are valid
+        {...divProps} // All HTMLDivElement props are valid
+
+    """
+
+    tag = "Html"
+
+
+class Pivot(SceneElement):
+    tag = "Pivot"
+
+
+class Movable(SceneElement):
+    tag = "Movable"
+
+
+class Obj(SceneElement):
+    tag = "Obj"
+
+    def __init__(self, src, mtl=None, materials=None, **kwargs):
+        """
+        :param src: The source of the obj file. Can be a url or a local file.
+        :type  src: str
+        :param mtlSrc: The source of the mtl file. Can be a url or a local file.
+        :type  mtlSrc: str
+        :param materials: A list of materials to be used for the obj file.
+        :type  materials: List[String]
+
+        todo: In the future we probably want to enable the loading of multiple material files.
+        """
+        self.src = src
+        self.mtl = mtl
+        self.materials = []
+
+        super().__init__(**kwargs)
+
+
+class CoordsMarker(SceneElement):
+    tag = "CoordsMarker"
+
+
+class Ply(SceneElement):
+    tag = "Ply"
+
+
+class Glb(SceneElement):
+    tag = "Glb"
+
+
+class Urdf(SceneElement):
+    tag = "Urdf"
+
+
+class Gripper(SceneElement):
+    tag = "Gripper"
+
+
+class SkeletalGripper(SceneElement):
+    tag = "SkeletalGripper"
+
+
+class Grid(SceneElement):
+    tag = "Grid"
+
+
+class GrabRender(SceneElement):
+    tag = "GrabRender"
+    key = "DEFAULT"
+    """We do not want the client to set keys automatically since GrabRender is 
+    usually used a singleton component as default."""
+
+
+class TimelineControls(SceneElement):
+    tag = "TimelineControls"
+    # todo: consider adding default component keys here.
+
+
+class PointerControls(SceneElement):
+    tag = "PointerControls"
+    # todo: consider adding default component keys here.
+
+
+class DefaultScene(Scene):
+    """Default Scene that includes a basic setup of ambient lights.
+
+
+    :param children: list of children elements to be rendered in the scene.
+    :type children: SceneElement, ...
+    :param rawChildren: list of children elements to be rendered in the scene.
+    :param htmlChildren: list of children elements to be rendered in the scene.
+    :param bgChildren: list of children elements to be rendered in the scene.
+    :param show_helper: list of children elements to be rendered in the scene.
+    :param startStep: list of children elements to be rendered in the scene.
+    :param endStep: list of children elements to be rendered in the scene.
+    :param up: list of children elements to be rendered in the scene.
+    :param kwargs: list of children elements to be rendered in the scene.
+
+    Example Usage::
+
+        DefaultScene(
+            # Ambient Light does not have helper because it is ambient.
+            AmbientLight(intensity=1.0, key="default_ambient_light"),
+            DirectionalLight(
+                intensity=1, key="default_directional_light", helper=show_helper
+            ),
+            *children,
+            rawChildren=rawChildren,
+            htmlChildren=htmlChildren,
+            bgChildren=[
+                GrabRender(),
+                *[
+                    # we use a key here so that we can replace the timeline controls via update
+                    TimelineControls(start=startStep, end=endStep, key="timeline")
+                    if endStep
+                    else None,
+                ],
+                PointerControls(),
+                Grid(),
+                *bgChildren,
+            ],
+            up=up,
+            **kwargs,
+        )
+    """
+
+    def __init__(
+        self,
+        *children: SceneElement,
+        rawChildren: List[SceneElement] = None,
+        htmlChildren: List[Element] = None,
+        bgChildren: List[SceneElement] = [],
+        show_helper=True,
+        startStep=0,
+        endStep=None,
+        # default to z-up
+        up=[0, 0, 1],
+        **kwargs,
+    ):
+        rawChildren = [
+            AmbientLight(intensity=1.0, key="default_ambient_light"),
+            DirectionalLight(intensity=1, key="default_directional_light", helper=show_helper),
+            *(rawChildren or []),
+        ]
+
+        super().__init__(
+            # Ambient Light does not have helper because it is ambient.
+            *children,
+            rawChildren=rawChildren,
+            htmlChildren=htmlChildren,
+            bgChildren=[
+                # skey spec here is a little redundant.
+                GrabRender(key="DEFAULT"),
+                *[
+                    # we use a key here so that we can replace the timeline controls via update
+                    TimelineControls(start=startStep, end=endStep, key="timeline")
+                    if endStep
+                    else None,
+                ],
+                PointerControls(),
+                Grid(),
+                *bgChildren,
+            ],
+            up=up,
+            **kwargs,
+        )

vuer/server.py

@@ -27,7 +27,7 @@ from vuer.events import (
     Upsert,
 )
 from vuer.schemas import Page
-from vuer.types import EventHandler, Spawnable
+from vuer.types import EventHandler, SocketHandler
 
 
 class At:
@@ -228,8 +228,36 @@ class VuerSession:
 
 
 class Vuer(PrefixProto, Server):
-    """
-    A Vuer is a document that can be rendered in a browser.
+    """Vuer Server
+
+    This is the server for the Vuer client.
+
+    Usage::
+
+        app = Vuer()
+
+        @app.spawn
+        async def main(session: VuerSession):
+             session.set @ Scene(children=[...])
+
+        app.run()
+
+
+    .. automethod:: bind
+    .. automethod:: spawn
+    .. automethod:: relay
+    .. automethod:: bound_fn
+    .. automethod:: spawn_task
+    .. automethod:: get_url
+    .. automethod:: send
+    .. automethod:: rpc
+    .. automethod:: rpc_stream
+    .. automethod:: close_ws
+    .. automethod:: uplink
+    .. automethod:: downlink
+    .. automethod:: add_handler
+    .. automethod:: _ttl_handler
+    .. automethod:: run
     """
 
     name = "vuer"
@@ -239,14 +267,12 @@ class Vuer(PrefixProto, Server):
     port = 8012
     free_port = True
     static_root = "."
-    queue_len = 100  # use a max lenth to avoid the momor from blowing up.
+    queue_len = 100  # use a max length to avoid the memory from blowing up.
     cors = "https://vuer.ai,https://dash.ml,http://localhost:8000,http://127.0.0.1:8000,*"
     queries = Proto({}, help="query parameters to pass")
 
     device = "cuda"
 
-    # need to be awaited
-
     def _proxy(self, ws_id) -> "VuerSession":
         """This is a proxy object that allows us to use the @ notation
         to send events to the client.
@@ -269,7 +295,7 @@ class Vuer(PrefixProto, Server):
         self.page = Page()
 
         self.ws = {}
-        self.spawned_fn: Spawnable = None
+        self.socket_handler: SocketHandler = None
         self.spawned_coroutines = []
 
     async def relay(self, request):
@@ -280,11 +306,11 @@ class Vuer(PrefixProto, Server):
 
         Interface:
             <uri>/relay?sid=<websocket_id>
+
         :return:
             - Status 200
             - Status 400
 
-
         """
         # todo: need to implement msgpack encoding, interface
         bytes = request.bytes()
@@ -340,20 +366,18 @@ class Vuer(PrefixProto, Server):
         loop = asyncio.get_running_loop()
         return loop.create_task(task)
 
-    def spawn(self, fn: Spawnable = None, start=False):
+    def spawn(self, fn: SocketHandler = None, start=False):
         """
-        Spawn a function as a task. This is useful in the following scenario:
-
-        code::
 
+        Note: this is really a misnomer.
 
         :param fn: The function to spawn.
         :param start: Start server after binding
         :return: None
         """
 
-        def wrap_fn(fn: Spawnable):
-            self.spawned_fn = fn
+        def wrap_fn(fn: SocketHandler):
+            self.socket_handler = fn
             if start:
                 self.run()
 
@@ -365,7 +389,7 @@ class Vuer(PrefixProto, Server):
 
     def bind(self, fn=None, start=False):
         """
-        Bind a function to the Tassa. The function should be a generator that yields Page objects.
+        Bind an asynchronous generator function for use in socket connection handler. The function should be a generator that yields Page objects.
 
         :param fn: The function to bind.
         :return: None
@@ -505,8 +529,8 @@ class Vuer(PrefixProto, Server):
 
         self._add_task(self.uplink(vuer_proxy))
 
-        if self.spawned_fn is not None:
-            task = self._add_task(self.spawned_fn(vuer_proxy))
+        if self.socket_handler is not None:
+            task = self._add_task(self.socket_handler(vuer_proxy))
 
         if hasattr(generator, "__anext__"):
             serverEvent = await generator.__anext__()
@@ -554,7 +578,7 @@ class Vuer(PrefixProto, Server):
     def add_handler(
         self,
         event_type: str,
-        fn: EventHandler,
+        fn: EventHandler = None,
         once: bool = False,
     ) -> Callable[[], None]:
         """Adding event handlers to the vuer server.
@@ -565,7 +589,29 @@ class Vuer(PrefixProto, Server):
             This is useful for RPC, which cleans up after itself.
             The issue is for RPC, the `key` also needs to match. So we hack it here to use
             a call specific event_type to enforce the cleanup.
+
+        # Usage:
+
+        As a decorator::
+
+            app = Vuer()
+            @app.add_handler("CAMERA_MOVE")
+            def on_camera(event: ClientEvent, session: VuerSession):
+                print("camera event", event.etype, event.value)
+
+        As a function::
+
+            app = Vuer()
+            def on_camera(event: ClientEvent, session: VuerSession):
+                print("camera event", event.etype, event.value)
+
+            app.add_handler("CAMERA_MOVE", on_camera)
+            app.run()
         """
+
+        if fn is None:
+            return lambda fn: self.add_handler(event_type, fn, once=once)
+
         handler_id = uuid4()
 
         def cleanup():

vuer/types.py

@@ -1,11 +1,29 @@
-from collections import namedtuple
 from typing import NamedTuple, Callable, Union, Coroutine
 from math import pi
+from typing import NamedTuple, Callable, Union, Coroutine
 from uuid import UUID
 
-from vuer.events import Event, ServerEvent, ClientEvent
+from vuer.events import ClientEvent
+
+IDType = Union[UUID, str]
+"""IDType is either a UUID or a string. Not in use."""
+
+CoroutineFn = Callable[[], Coroutine]
+"""A function that returns a coroutine. Not in use."""
+
+# SendProxy = Callable[[ServerEvent], None]
+EventHandler = Callable[[ClientEvent, "VuerProxy"], None]
+"""Defines a function that handles a client event. Second argument is the VuerProxy instance bound
+to a specific client connected through a websocket session."""
+
+SocketHandler = Callable[["VuerProxy"], Coroutine]
+"""Defines a function that spawns a new entity. Argument is the VuerProxy instance."""
 
-Vector3 = namedtuple("Vector3", ["x", "y", "z"])
+
+class Vector3(NamedTuple):
+    x: int
+    y: int
+    z: int
 
 
 class Euler(NamedTuple):
@@ -13,7 +31,6 @@ class Euler(NamedTuple):
     y: int
     z: int
     order: str = "XYZ"
-    # unit: str = "rad"
 
 
 class EulerDeg(Euler):
@@ -23,27 +40,12 @@ class EulerDeg(Euler):
         return Euler(*[v / 180 * pi for v in self[:3]], order=self.order)
 
 
-# class EulerRad(Euler):
-#     unit: str = "rad"
-
-
 class Body(NamedTuple):
     position: Vector3
     rotation: Euler
     scale: float
 
 
-class RenderNode:
-    pass
-
-
-IDType = Union[UUID, str]
-CoroutineFn = Callable[[], Coroutine]
-
-# SendProxy = Callable[[ServerEvent], None]
-EventHandler = Callable[[ClientEvent, "VuerProxy"], None]
-Spawnable = Callable[["VuerProxy"], Coroutine]
-
 if __name__ == "__main__":
     e = Euler(x=1, y=2, z=3)
     assert e[:3] == (1, 2, 3)

{vuer-0.0.16.dist-info → vuer-0.0.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vuer
-Version: 0.0.16
+Version: 0.0.18
 Home-page: https://github.com/geyang/vuer
 Author: Ge Yang<ge.ike.yang@gmail.com>
 Author-email: ge.ike.yang@gmail.com

vuer-0.0.18.dist-info/RECORD

@@ -0,0 +1,37 @@
+vuer/__init__.py,sha256=HMgKfbQAW77ukrMOnE2oKNOYbSNEkBwElpkWxLofvP8,41
+vuer/base.py,sha256=R-PtD39ouihiEGmSfJL26chlU0XkFJP-JmBNYzDdEvM,3068
+vuer/events.py,sha256=8AAzkfbm5jHkeMh17Z57n8YTxF4mheWC3Qbya4XkQSc,7291
+vuer/schemas.py,sha256=aZOocE02gO43SLLfeYSxxac0x38TmyTcfs_iFh5hsJ4,18152
+vuer/serdes.py,sha256=gD2iA9Yypu1QjocneOT3Nc0y6q_mdHn9zW1ko5j3I7c,2600
+vuer/server.py,sha256=OsXSq6iScFTG-yvAXWAik-EwNwEKdd1F84nUqBwyrjE,19955
+vuer/types.py,sha256=N2KLa0fl6z8Jm6cJwZoD8Vqrins_AayG5BCGk1p3Eek,1279
+vuer/__pycache__/__init__.cpython-38.pyc,sha256=rS-9zzAjFEXnObk5q3E5Rex_uvoJ-Ccfz7Hs9DGNVgs,188
+vuer/__pycache__/base.cpython-38.pyc,sha256=Z5EFlRX9RqZsQUszvqPtAhLv_5QG5wlUXW7JbFd_XDc,3824
+vuer/__pycache__/events.cpython-38.pyc,sha256=zx3bXeJixqOyCFe2nA7qpq6jiCJ49kRaXO-xONGUyeQ,9616
+vuer/__pycache__/schemas.cpython-38.pyc,sha256=hvY9Aak8zE-zKcWiwuNe6DghOw9qH_zSe_FtkBOAPPk,23234
+vuer/__pycache__/serdes.cpython-38.pyc,sha256=KMxTjPEWuSGn2bqBAl5OLIDSCSoqfPDGfk3fvNnRDYA,2253
+vuer/__pycache__/server.cpython-38.pyc,sha256=kAsC8t-JgTOOccZMaXZMEqgTSV3C3T5Oyj1sl-QABM4,18696
+vuer/__pycache__/types.cpython-38.pyc,sha256=IhlXtkT-XWM0V1420FDuoqIYnpvRvekYVkGqEK7fAV8,1819
+vuer/addons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vuer/addons/nerf_vuer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vuer/addons/nerf_vuer/control_components.py,sha256=K4PU0nD572L4J7lLFfShWficWZQnH4t-x6WWMrAVw8g,290
+vuer/addons/nerf_vuer/mixins.py,sha256=fQuW3adf6X2xw_PSfS145TNfbQ9OoTKuv8mYEo6Pt6A,12966
+vuer/addons/nerf_vuer/nerf_vuer.py,sha256=R5vI7g_sObbW1LTZ2VnR7pci7aO8iUtkKIbNnbqHnRU,5183
+vuer/addons/nerf_vuer/render_components.py,sha256=XilHnJySJWVgmdUbPFNYyc_YWV8O5AcKkBEZOUFbnMI,3821
+vuer/addons/nerf_vuer/render_nodes.py,sha256=5TKqIbMPiOtBxfF4FQI6uB0w_9FTfGiwS8xRbhPa0_g,14441
+vuer/addons/nerfuer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vuer/addons/nerfuer/render_nodes.py,sha256=EJK5N3xne5n7abTaAoLPX7SRqQ_tEen9zNypvSnZTTw,4465
+vuer/schemas/__init__.py,sha256=ZI6UyeLZXqJbHmp6LiE3Q3mHvt1zeV-SJmmcqq-wBZE,94
+vuer/schemas/drei_components.py,sha256=U9svEOnNprhZaobLagaFnqEtZxo5hiriSqjDnvQutoA,6989
+vuer/schemas/html_components.py,sha256=NCqmSPic-ExPrXqNPXbKjtTXMB8sGBywIpE6cXpiy08,5926
+vuer/schemas/scene_components.py,sha256=L9GbgFnrhxUYKi4EyexaAun7gmn6aHnCQIeSGSGwIRU,14913
+vuer/schemas/__pycache__/__init__.cpython-38.pyc,sha256=NRnVrpIDBKne93xOUY1-WpavCG7vwYiqU3VDTEEwuUE,221
+vuer/schemas/__pycache__/drei_components.cpython-38.pyc,sha256=g_ufcKxf-XKfZLdUV-HqKnjIrgxGWFv51aHLWQgH-ws,7712
+vuer/schemas/__pycache__/html_components.cpython-38.pyc,sha256=q0DMFwNkYbnaH1A8w3BowMiQAlmGpFWOOKsjLVE6CIk,8215
+vuer/schemas/__pycache__/scene_components.cpython-38.pyc,sha256=eRxB-Tp24yqBR4zbLMGX_4o1P_D-tW1nrDeBPSJKoU4,18135
+vuer-0.0.18.dist-info/LICENSE,sha256=MGF-inVBUaGe2mEjqT0g6XsHIXwoNXgNHqD7Z1MzR0k,1063
+vuer-0.0.18.dist-info/METADATA,sha256=cbpGK1fH2Wx_FmSLe_X9M59Dk0E_V-7v5FCS-KRfvx0,4277
+vuer-0.0.18.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
+vuer-0.0.18.dist-info/entry_points.txt,sha256=J_NM6fbpipmD9oP7cdxd1UyBR8mVEQVx0xjlE_56yss,41
+vuer-0.0.18.dist-info/top_level.txt,sha256=ermmVkwvGFAK4gfSgDIwOmKpxwpqNt-oo7gVQQUSHok,5
+vuer-0.0.18.dist-info/RECORD,,

vuer-0.0.16.dist-info/RECORD

@@ -1,29 +0,0 @@
-vuer/__init__.py,sha256=HMgKfbQAW77ukrMOnE2oKNOYbSNEkBwElpkWxLofvP8,41
-vuer/base.py,sha256=R-PtD39ouihiEGmSfJL26chlU0XkFJP-JmBNYzDdEvM,3068
-vuer/events.py,sha256=2N6B9sYkxxVv6BhegBq-dIc8mxb3A42lgJz-pD1MCRU,7272
-vuer/schemas.py,sha256=aZOocE02gO43SLLfeYSxxac0x38TmyTcfs_iFh5hsJ4,18152
-vuer/serdes.py,sha256=gD2iA9Yypu1QjocneOT3Nc0y6q_mdHn9zW1ko5j3I7c,2600
-vuer/server.py,sha256=YsLywahKIO75lgp4ZBuWkuQ-rxFURbVQiPYQDHluzG0,18752
-vuer/types.py,sha256=YpRQrBzB2uGM1Lhu8eSaBGB88IgSnY4Czl5cgthxGkM,1003
-vuer/__pycache__/__init__.cpython-38.pyc,sha256=rS-9zzAjFEXnObk5q3E5Rex_uvoJ-Ccfz7Hs9DGNVgs,188
-vuer/__pycache__/base.cpython-38.pyc,sha256=Z5EFlRX9RqZsQUszvqPtAhLv_5QG5wlUXW7JbFd_XDc,3824
-vuer/__pycache__/events.cpython-38.pyc,sha256=d8eqZPmim4QsTts1dkNmWmjcV4jbULFB3VjjqcHOtxo,9612
-vuer/__pycache__/schemas.cpython-38.pyc,sha256=hvY9Aak8zE-zKcWiwuNe6DghOw9qH_zSe_FtkBOAPPk,23234
-vuer/__pycache__/serdes.cpython-38.pyc,sha256=KMxTjPEWuSGn2bqBAl5OLIDSCSoqfPDGfk3fvNnRDYA,2253
-vuer/__pycache__/server.cpython-38.pyc,sha256=HHbFWxrJL-cbHD2JNoRBiU2B7SJFec8PYb5qFPZupVQ,17416
-vuer/__pycache__/types.cpython-38.pyc,sha256=eM6bZ35nB-AYALbZXf9goHjLoHxllqbIwHloi0yCOeA,1868
-vuer/addons/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vuer/addons/nerf_vuer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vuer/addons/nerf_vuer/control_components.py,sha256=K4PU0nD572L4J7lLFfShWficWZQnH4t-x6WWMrAVw8g,290
-vuer/addons/nerf_vuer/mixins.py,sha256=fQuW3adf6X2xw_PSfS145TNfbQ9OoTKuv8mYEo6Pt6A,12966
-vuer/addons/nerf_vuer/nerf_vuer.py,sha256=R5vI7g_sObbW1LTZ2VnR7pci7aO8iUtkKIbNnbqHnRU,5183
-vuer/addons/nerf_vuer/render_components.py,sha256=XilHnJySJWVgmdUbPFNYyc_YWV8O5AcKkBEZOUFbnMI,3821
-vuer/addons/nerf_vuer/render_nodes.py,sha256=5TKqIbMPiOtBxfF4FQI6uB0w_9FTfGiwS8xRbhPa0_g,14441
-vuer/addons/nerfuer/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-vuer/addons/nerfuer/render_nodes.py,sha256=EJK5N3xne5n7abTaAoLPX7SRqQ_tEen9zNypvSnZTTw,4465
-vuer-0.0.16.dist-info/LICENSE,sha256=MGF-inVBUaGe2mEjqT0g6XsHIXwoNXgNHqD7Z1MzR0k,1063
-vuer-0.0.16.dist-info/METADATA,sha256=629n5RfSb8ZXofvd-3McLXSjN9CQItqoK7Q8I7byInY,4277
-vuer-0.0.16.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
-vuer-0.0.16.dist-info/entry_points.txt,sha256=J_NM6fbpipmD9oP7cdxd1UyBR8mVEQVx0xjlE_56yss,41
-vuer-0.0.16.dist-info/top_level.txt,sha256=ermmVkwvGFAK4gfSgDIwOmKpxwpqNt-oo7gVQQUSHok,5
-vuer-0.0.16.dist-info/RECORD,,