MeshCat.jl
API Reference
MeshCat.AbstractVisualizer
— TypeAbstract parent type of MeshCat.Visualizer
.
MeshCat.Animation
— TypeCreate a new animation. See atframe
to adjust object poses or properties in that animation.
Animation() -> Animation
Animation(fps::Int64) -> Animation
MeshCat.ArrowVisualizer
— TypeHelper type for rendering arrows in the visualizer.
Usage:
Given a Visualizer
named vis
, we can create an arrow with:
ArrowVisualizer arrow(vis)
setobject!(arrow)
We can then set the base and direction of the arrow with:
settransform!(arrow, Point(0.0, 0.0, 0.0), Vec(0.5, 0.5, 0.0))
Note that this settransform!
should work correctly inside an Animation
, as long as you do setobject!
before starting the animation.
MeshCat.Cone
— TypeA 3D cone, represented by the position of the origin of its base, the position of its tip, and the radius of its base.
MeshCat.HyperEllipsoid
— TypeN-dimensional ellipsoid. Note that only N=3 dimensional ellipsoids can be rendered in the visualizer.
MeshCat.MeshFileGeometry
— TypeAn MeshFileGeometry represents a mesh which is stored as the raw contents of a file, rather than as a collection of points and vertices. This is useful for transparently passing mesh files which we can't load in Julia directly to meshcat.
Supported formats: * .stl (ASCII and binary) * .obj * .dae (Collada)
For .obj and .dae files, only a single mesh geometry will be loaded, and any material or texture properties will be ignored. To load an entire collection of objects (complete with materials and textures) from an .obj or .dae file, see MeshFileObject instead.
MeshCat.MeshFileObject
— TypeA MeshFileObject is similar to a MeshFileGeometry, but rather than representing a single geometry, it supports loading an entire object (with geometries, materials, and textures), or even a collection of objects (for supported file types).
Supported formats: * .obj * .dae (Collada)
Since mesh files may include references to other files (such as texture images), the MeshFileObject also includes a resources
dictionary mapping relative paths (as specified in the mesh file) to the contents of the referenced files. Those contents are specified using data URIs, e.g.:
data:image/png;base64,<base-64 encoded data here>
If you construct a MeshFileObject from a .dae
or .obj
file, the resources dictionary will automatically be populated.
MeshCat.Object
— TypeRepresents a three.js Object, consisting of a geometry and a material.
MeshCat.PointCloud
— TypeA collection of points which will be rendered as a point cloud in the visualiezr.
You can set the color of each point indepenedntly when you construct a PointCloud, or you can set the overall point color by passing a PointsMaterial
as the material when you call setobject!(vis, point_cloud, material)
MeshCat.Triad
— TypeA visual representation of the origin of a coordinate system, drawn as three lines in red, green, and blue along the x, y, and z axes. The scale
parameter controls the length of the three lines.
MeshCat.Visualizer
— Typevis = Visualizer()
Construct a new MeshCat visualizer instance.
Useful methods:
vis[:group1] # get a new visualizer representing a sub-tree of the scene
setobject!(vis, geometry) # set the object shown by this visualizer's sub-tree of the scene
settransform!(vis, tform) # set the transformation of this visualizer's sub-tree of the scene
setvisible!(vis, false) # hide this part of the scene
Base.delete!
— MethodDelete the geometry at this visualizer's path and all of its descendants.
delete!(vis::Visualizer) -> Visualizer
MeshCat.atframe
— MethodCall the given function f
, but intercept any settransform!
or setprop!
calls and apply them to the given animation at the given frame instead.
atframe(f::Any, animation::Animation, frame::Integer) -> Animation
Usage:
vis = Visualizer()
setobject!(vis[:cube], Rect(Vec(0.0, 0.0, 0.0), Vec(0.5, 0.5, 0.5)))
anim = Animation()
# At frame 0, set the cube's position to be the origin
atframe(anim, 0) do
settransform!(vis[:cube], Translation(0.0, 0.0, 0.0))
end
# At frame 30, set the cube's position to be [1, 0, 0]
atframe(anim, 30) do
settransform!(vis[:cube], Translation(1.0, 0.0, 0.0))
end
setanimation!(vis, anim)
MeshCat.render
— MethodRender a MeshCat visualizer inline in Jupyter, Juno, or VSCode.
If this is the last command in a Jupyter notebook cell, then the visualizer should show up automatically in the corresponding output cell.
If this is run from the Juno console, then the visualizer should show up in the Juno plot pane. Likewise if this is run from VSCode with the julia-vscode extension, then the visualizer should show up in the Julia Plots pane.
MeshCat.render_static
— MethodRender a static version of the visualizer, suitable for embedding and offline use. The embedded visualizer includes all geometries, properties, and animations which have been added to the scene, baked into a single HTML document. This document also includes the full compressed MeshCat javascript source files, so it should render properly even after you've exited Julia and even if you have no internet access.
To get access to the raw static HTML representation, see static_html
MeshCat.save_image
— MethodTakes a screenshot of the current visualizer and saves it as an image to the disk.
save_image(vis::Visualizer) -> Visualizer
MeshCat.setanimation!
— MethodSet the currently playing animation in the visualizer.
setanimation!(vis::Visualizer, anim::Animation; play, repetitions)
MeshCat.setobject!
— Methodsetobject!(vis::AbstractVisualizer, geom::Union{GeometryBasics.AbstractGeometry, GeometryBasics.AbstractMesh, MeshFileGeometry}, material::AbstractMaterial) -> Visualizer
This will construct an appropriate three.js object from the given geometry and the given material.
MeshCat.setobject!
— Methodsetobject!(vis::AbstractVisualizer, geom::Union{GeometryBasics.AbstractGeometry, GeometryBasics.AbstractMesh, MeshFileGeometry}) -> Visualizer
This will construct an appropriate three.js object from the given geometry and a default material.
MeshCat.setobject!
— MethodSet the object at this visualizer's path. This replaces whatever geometry was presently at that path.
setobject!(vis::Visualizer, obj::AbstractObject) -> Visualizer
To draw multiple geometries, place them at different paths by using the slicing notation:
setobject!(vis[:group1][:box1], geometry1)
setobject!(vis[:group1][:box2], geometry2)
MeshCat.setprop!
— MethodSet a single property for the object at the given path.
setprop!(vis::Visualizer, property::AbstractString, value::Any) -> Visualizer
(this is named setprop! instead of setproperty! to avoid confusion with the Base.setproperty! function introduced in Julia v0.7)
MeshCat.settransform!
— MethodSet the transform of this visualizer's path. This can be done before or after adding an object at that path.
settransform!(vis::Visualizer, tform::CoordinateTransformations.Transformation) -> Visualizer
The overall transform of an object is the composition of the transforms of all of its parents, so setting the transform of vis[:group1]
affects the poses of the objects at vis[:group1][:box1]
and vis[:group1][:box2]
.
MeshCat.setvisible!
— MethodToggle visibility of the visualizer at the current path.
setvisible!(vis::AbstractVisualizer, visible::Bool) -> Visualizer
MeshCat.static_html
— MethodExtract a single HTML document containing the entire MeshCat scene, including all geometries, properties, and animations, as well as all required javascript assets. The resulting HTML document should render correctly after you've exited Julia, and even if you have no internet access.
MeshCat.CoreVisualizer
— TypeLow-level type which manages the actual meshcat server. See Visualizer
for the public-facing interface.
Base.getindex
— MethodGet a new Visualizer
representing a sub-tree of the same scene.
getindex(vis::Visualizer, path::Vararg{Any,N} where N) -> Visualizer
For example, if you have vis::Visualizer
with path /meshcat/foo
, you can do vis[:bar]
to get a new Visualizer
with path /meshcat/foo/bar
.
Base.merge!
— MethodMerge multiple animations, storing the result in a
.
merge!(a::Animation, others::Vararg{Animation,N} where N) -> Animation
Base.merge
— MethodMerge two or more animations, returning a new animation.
merge(a::Animation, others::Vararg{Animation,N} where N) -> Animation
The animations may involve the same properties or different properties (animations of the same property on the same path will have their events interleaved). All animations must have the same framerate.
Base.open
— MethodOpen the visualizer. By default, this will launch your default web browser pointing to the visualizer's URL.
Base.wait
— Methodwait(v::Visualizer)
Wait until at least one browser has connected to the visualizer's server. This is useful in scripts to delay execution until the browser window has opened.
MeshCat.convert_frames_to_video
— FunctionConvert the .tar
file of still images produced by the meshcat "record" feature into a video.
convert_frames_to_video(tar_file_path::AbstractString) -> Any
convert_frames_to_video(tar_file_path::AbstractString, output_path::AbstractString; framerate, overwrite) -> Any
To record an animation which has been played in the meshcat visualizer, click "Open Controls", then navigate to the "Animations" folder and click "record". This will step through the animation frame-by-frame and then prompt you to download a .tar
file containing the resulting frames. You can then pass the path to that .tar
file to this function to produce a video.
This uses FFMPEG.jl internally, so you do not need to have installed ffmpeg manually.
MeshCat.develop_meshcat_assets
— FunctionUse git to clone the meshcat javascript assets repository for local development.
develop_meshcat_assets()
develop_meshcat_assets(skip_confirmation)
You should only do this if you plan on editing the javascript or HTML components of meshcat itself. To undo this operation, you will need to delete the assets/meshcat
folder and then run using Pkg; Pkg.build("MeshCat")
MeshCat.intrinsic_transform
— Methodintrinsic_transform(g)
Different tools disagree about what various geometric primitives mean. For example, GeometryBasics.jl considers the "origin" of a cube to be its bottom-left corner, where DrakeVisualizer and MeshCat consider its origin to be the center. The intrinsic_transform(g) returns the transform from the GeometryBasics origin to the MeshCat origin.
MeshCat.lower
— FunctionConvert a geometry, material, object, or transform into the appropriate plain data structures expected by three.js. Most objects are lowered into Dict
s matching the JSON structure used by three.js.
MeshCat.lower
— MethodFallback for everything else (like Polyhedra.jl's Polyhedron types)
lower(g::GeometryBasics.GeometryPrimitive) -> Dict{String,Any}
MeshCat.mergesorted!
— Methodmergesorted!(dest::AbstractVector, a, b; by=identity, lt=isless)
Merge sorted iterators a
and b
, storing the result in dest
. dest
should be of the appropriate length to store all elements of a
and b
; it is not resized.
For equivalent elements in a
and b
, the elements from a
(preserving their original order) precede the elements from b
(preserving their original order).
Elements are compared by (x, y) -> lt(by(x), by(y))
The behavior is undefined if dest
overlaps a
or b
(though the a
and b
may overlap each other) or if a
or b
are not sorted.
Adapted from https://en.cppreference.com/w/cpp/algorithm/merge.