Plot geometry

Create, load, update, and remove a plot

NpOptiX.get_geometry_names() → list[source]

Return list of geometries’ names.

NpOptiX.set_data(name: str, pos: Optional[Any] = None, r: Optional[Any] = None, c: Optional[Any] = None, u: Optional[Any] = None, v: Optional[Any] = None, w: Optional[Any] = None, geom: Union[plotoptix.enums.Geometry, str] = <Geometry.ParticleSet: 1>, geom_attr: Union[plotoptix.enums.GeomAttributeProgram, str] = <GeomAttributeProgram.Default: 0>, mat: Optional[str] = None, rnd: bool = True) → None[source]

Create new or update existing geometry for the dataset.

Data is provided as an array of 3D positions of data points, with the shape (n, 3). Additional features can be visualized as a color and size/thickness of the primitives.

Note: not all arguments are used to update existing geeometry. Update is available for: mat, pos, c, r, u, v, and w data.

Parameters
  • name (string) – Name of the geometry.

  • pos (array_like, optional) – Positions of data points.

  • c (Any, optional) – Colors of the primitives. Single value means a constant gray level. 3-component array means constant RGB color. Array with the shape[0] equal to the number of primitives will set individual gray/color for each primitive.

  • r (Any, optional) – Radii of particles / bezier primitives or U / V / W lengths of parallelograms / parallelepipeds / tetrahedrons (if u / v / w not provided). Single value sets const. size for all primitives.

  • u (array_like, optional) – U vector(s) of parallelograms / parallelepipeds / tetrahedrons / textured particles. Single vector sets const. value for all primitives.

  • v (array_like, optional) – V vector(s) of parallelograms / parallelepipeds / tetrahedrons / textured particles. Single vector sets const. value for all primitives.

  • w (array_like, optional) – W vector(s) of parallelepipeds / tetrahedrons. Single vector sets const. value for all primitives.

  • geom (Geometry enum or string, optional) – Geometry of primitives (ParticleSet, Tetrahedrons, …). See plotoptix.enums.Geometry enum.

  • geom_attr (GeomAttributeProgram enum or string, optional) – Geometry attributes program. See plotoptix.enums.GeomAttributeProgram enum.

  • mat (string, optional) – Material name.

  • rnd (bool, optional) – Randomize not provided U / V / W vectors so regular but randomly rotated primitives are generated using available vectors (default). If set to False all primitives are aligned in the same direction.

NpOptiX.update_data(name: str, mat: Optional[str] = None, pos: Optional[Any] = None, c: Optional[Any] = None, r: Optional[Any] = None, u: Optional[Any] = None, v: Optional[Any] = None, w: Optional[Any] = None) → None[source]

Update data of an existing geometry.

Note that on data size changes (pos array size different than provided with plotoptix.NpOptiX.set_data()) also other properties must be provided matching the new size, otherwise default values are used.

Parameters
  • name (string) – Name of the geometry.

  • mat (string, optional) – Material name.

  • pos (array_like, optional) – Positions of data points.

  • c (Any, optional) – Colors of the primitives. Single value means a constant gray level. 3-component array means constant RGB color. Array with the shape[0] equal to the number of primitives will set individual grey/color for each primitive.

  • r (Any, optional) – Radii of particles / bezier primitives. Single value sets constant radius for all primitives.

  • u (array_like, optional) – U vector(s) of parallelograms / parallelepipeds / tetrahedrons / textured particles. Single vector sets const. value for all primitives.

  • v (array_like, optional) – V vector(s) of parallelograms / parallelepipeds / tetrahedrons / textured particles. Single vector sets const. value for all primitives.

  • w (array_like, optional) – W vector(s) of parallelepipeds / tetrahedrons. Single vector sets const. value for all primitives.

NpOptiX.set_data_2d(name: str, pos: Optional[Any] = None, r: Optional[Any] = None, c: Optional[Any] = None, normals: Optional[Any] = None, range_x: Optional[Tuple[float, float]] = None, range_z: Optional[Tuple[float, float]] = None, floor_y: Optional[float] = None, floor_c: Optional[Any] = None, geom: Union[plotoptix.enums.Geometry, str] = <Geometry.Mesh: 10>, mat: Optional[str] = None, make_normals: bool = False) → None[source]

Create new or update existing surface geometry for the 2D dataset.

Data is provided as 2D array of \(z = f(x, y)\) values, with the shape (n, m), where n and m are at least 2. Additional data features can be visualized with color (array of RGB values, shape (n, m, 3)).

Convention of vertical Y and horizontal XZ plane is adopted.

Note: not all arguments are used to update existing geeometry. Update is available for: mat, pos, c, r, normals, range_x, range_z, floor_y, and floor_c data.

Parameters
  • name (string) – Name of the new surface geometry.

  • pos (array_like, optional) – Z values of data points.

  • r (Any, optional) – Radii of vertices for the plotoptix.enums.Geometry.Graph geometry, interpolated along the wireframe edges. Single value sets constant radius for all vertices.

  • c (Any, optional) – Colors of data points. Single value means a constant gray level. 3-component array means a constant RGB color. Array of the shape (n, m, 3) will set individual color for each data point, interpolated between points; n and m have to be the same as in data points shape.

  • normals (array_like, optional) – Surface normal vectors at data points. Array shape has to be (n, m, 3), with n and m the same as in data points shape.

  • range_x (tuple (float, float), optional) – Data range along X axis. Data array indexes are used if range is not provided.

  • range_z (tuple (float, float), optional) – Data range along Z axis. Data array indexes are used if range is not provided.

  • floor_y (float, optional) – Y level of XZ plane forming the base of the new geometry. Surface only is created if floor_y is not provided.

  • floor_c (Any, optional) – Color of the base volume. Single value or array_like RGB color values.

  • geom (Geometry enum or string, optional) – Geometry of the surface, only plotoptix.enums.Geometry.Mesh or plotoptix.enums.Geometry.Graph are supported.

  • mat (string, optional) – Material name.

  • make_normals (bool, optional) – Calculate normals for data points, only if not provided with normals argument. Normals of all triangles attached to the point are averaged.

NpOptiX.update_data_2d(name: str, mat: Optional[str] = None, pos: Optional[Any] = None, r: Optional[Any] = None, c: Optional[Any] = None, normals: Optional[Any] = None, range_x: Optional[Tuple[float, float]] = None, range_z: Optional[Tuple[float, float]] = None, floor_y: Optional[float] = None, floor_c: Optional[Any] = None) → None[source]

Update surface geometry data or properties.

Parameters
  • name (string) – Name of the surface geometry.

  • mat (string, optional) – Material name.

  • pos (array_like, optional) – Z values of data points.

  • r (Any, optional) – Radii of vertices for the plotoptix.enums.Geometry.Graph geometry, interpolated along the wireframe edges. Single value sets constant radius for all vertices.

  • c (Any, optional) – Colors of data points. Single value means a constant gray level. 3-component array means a constant RGB color. Array of the shape (n,m,3) will set individual color for each data point, interpolated between points; n and m have to be the same as in data points shape.

  • normals (array_like, optional) – Surface normal vectors at data points. Array shape has to be (n,m,3), with n and``m`` the same as in data points shape.

  • range_x (tuple (float, float), optional) – Data range along X axis.

  • range_z (tuple (float, float), optional) – Data range along Z axis.

  • floor_y (float, optional) – Y level of XZ plane forming the base of the geometry.

  • floor_c (Any, optional) – Color of the base volume. Single value or array_like RGB color values.

NpOptiX.set_surface(name: str, pos: Optional[Any] = None, r: Optional[Any] = None, c: Optional[Any] = None, normals: Optional[Any] = None, geom: Union[plotoptix.enums.Geometry, str] = <Geometry.Mesh: 10>, mat: Optional[str] = None, wrap_u: bool = False, wrap_v: bool = False, make_normals: bool = False) → None[source]

Create new or update existing parametric surface geometry.

Data is provided as 2D array of \([x, y, z] = f(u, v)\) values, with the shape (n, m, 3), where n and m are at least 2. Additional data features can be visualized with color (array of RGB values, shape (n, m, 3)) or wireframe thickness if the plotoptix.enums.Geometry.Graph geometry is used.

Note: not all arguments are used to update existing geeometry. Update is available for: mat, pos, c, r, and normals data.

Parameters
  • name (string) – Name of the new surface geometry.

  • pos (array_like, optional) – XYZ values of surface points.

  • r (Any, optional) – Radii of vertices for the plotoptix.enums.Geometry.Graph geometry, interpolated along the wireframe edges. Single value sets constant radius for all vertices.

  • c (Any, optional) – Colors of surface points. Single value means a constant gray level. 3-component array means a constant RGB color. Array of the shape (n, m, 3) will set individual color for each surface point, interpolated between points; n and m have to be the same as in the surface points shape.

  • normals (array_like, optional) – Normal vectors at provided surface points. Array shape has to be (n, m, 3), with n and m the same as in the surface points shape.

  • geom (Geometry enum or string, optional) – Geometry of the surface, only plotoptix.enums.Geometry.Mesh or plotoptix.enums.Geometry.Graph are supported.

  • mat (string, optional) – Material name.

  • wrap_u (bool, optional) – Stitch surface edges making U axis continuous.

  • wrap_v (bool, optional) – Stitch surface edges making V axis continuous.

  • make_normals (bool, optional) – Calculate normals for surface points, only if not provided with normals argument. Normals of all triangles attached to the point are averaged.

NpOptiX.update_surface(name: str, mat: Optional[str] = None, pos: Optional[Any] = None, r: Optional[Any] = None, c: Optional[Any] = None, normals: Optional[Any] = None) → None[source]

Update surface geometry data or properties.

Parameters
  • name (string) – Name of the surface geometry.

  • mat (string, optional) – Material name.

  • pos (array_like, optional) – XYZ values of surface points.

  • r (Any, optional) – Radii of vertices for the plotoptix.enums.Geometry.Graph geometry, interpolated along the edges. Single value sets constant radius for all vertices.

  • c (Any, optional) – Colors of surface points. Single value means a constant gray level. 3-component array means a constant RGB color. Array of the shape (n, m, 3) will set individual color for each surface point, interpolated between points; n and m have to be the same as in the surface points shape.

  • normals (array_like, optional) – Normal vectors at provided surface points. Array shape has to be (n, m, 3), with n and m the same as in the surface points shape.

NpOptiX.set_mesh(name: str, pos: Optional[Any] = None, faces: Optional[Any] = None, c: Any = array([0.94, 0.94, 0.94], dtype=float32), normals: Optional[Any] = None, nidx: Optional[Any] = None, uvmap: Optional[Any] = None, uvidx: Optional[Any] = None, mat: str = 'diffuse', make_normals: bool = False) → None[source]

Create new or update existing mesh geometry.

Data is provided as vertices \([x, y, z]\), with the shape (n, 3), and faces (triplets of vertex indices), with the shape (n, 3) or (m) where \(m = 3*n\). Data features can be visualized with color (array of RGB values assigned to the mesh vertices, shape (n, 3)).

Mesh normals can be provided as an array of 3D vectors. Mappng of normals to faces can be provided as an array of nidx indexes. If mapping is not provided then face vertex data is used (requires same number of vertices and normal vectors).

Smooth shading normals can be pre-calculated if make_normals=True and normals data is not provided.

Texture UV mapping uvmap can be provided as an array of 2D vectors. Mappng of UV coordinates to faces can be provided as an array of uvidx indexes. If mapping is not provided then face vertex data is used (requires same number of vertices and UV points).

Note: not all arguments are used to update existing geeometry. Update is available for: mat, pos, faces, c, normals, nidx, uvmap and uvidx data.

Parameters
  • name (string) – Name of the new mesh geometry.

  • pos (array_like, optional) – XYZ values of the mesh vertices.

  • faces (array_like, optional) – Mesh faces as indices (triplets) to the pos array.

  • c (Any, optional) – Colors of mesh vertices. Single value means a constant gray level. 3-component array means a constant RGB color. Array of the shape (n, 3) will set individual color for each vertex, interpolated on face surfaces; n has to be equal to the vertex number in pos array.

  • normals (array_like, optional) – Normal vectors.

  • nidx (array_like, optional) – Normal to face mapping, faces is used if not provided.

  • uvmap (array_like, optional) – Texture UV coordinates.

  • uvidx (array_like, optional) – Texture UV to face mapping, faces is used if not provided.

  • mat (string, optional) – Material name.

  • make_normals (bool, optional) – Calculate smooth shading of the mesh, only if normals are not provided. Normals of all triangles attached to the mesh vertex are averaged.

NpOptiX.update_mesh(name: str, mat: Optional[str] = None, pos: Optional[Any] = None, faces: Optional[Any] = None, c: Optional[Any] = None, normals: Optional[Any] = None, nidx: Optional[Any] = None, uvmap: Optional[Any] = None, uvidx: Optional[Any] = None) → None[source]

Update data of an existing mesh geometry.

All data or only some of arrays may be uptated. If vertices and faces are left unchanged then other arrays sizes should match the sizes of the mesh, i.e. c shape should match existing pos shape, nidx and uvidx shapes should match faces shape or if index mapping is not provided then normals and uvmap shapes should match pos shape.

Parameters
  • name (string) – Name of the mesh geometry.

  • mat (string, optional) – Material name.

  • pos (array_like, optional) – XYZ values of the mesh vertices.

  • faces (array_like, optional) – Mesh faces as indices (triplets) to the pos array.

  • c (Any, optional) – Colors of mesh vertices. Single value means a constant gray level. 3-component array means a constant RGB color. Array of the shape (n, 3) will set individual color for each vertex, interpolated on face surfaces; n has to be equal to the vertex number in pos array.

  • normals (array_like, optional) – Normal vectors.

  • nidx (array_like, optional) – Normal to face mapping, existing mesh faces is used if not provided.

  • uvmap (array_like, optional) – Texture UV coordinates.

  • uvidx (array_like, optional) – Texture UV to face mapping, existing mesh faces is used if not provided.

NpOptiX.load_mesh_obj(file_name: str, mesh_name: Optional[str] = None, parent: Optional[str] = None, c: Any = array([0.94, 0.94, 0.94], dtype=float32), mat: str = 'diffuse', make_normals: bool = False) → None[source]

Load mesh geometry from Wavefront .obj file.

Note: this method can read files with named objects only. Use plotoptix.NpOptiX.load_merged_mesh_obj() for reading files with raw, unnamed mesh.

Parameters
  • file_name (string) – File name (local file path or url) to read from.

  • mesh_name (string, optional) – Name of the mesh to import from the file. All meshes are imported if None value or empty string is used.

  • parent (string, optional) – Optional name of a mesh to set as a parent of all other meshes loaded from the file. All transformations applied to the parent will be applied to children meshes as well.

  • c (Any, optional) – Color of the mesh. Single value means a constant gray level. 3-component array means constant RGB color.

  • mat (string, optional) – Material name.

  • make_normals (bool, optional) – If set to True and .obj file does not contain normals then normals are calculated for each vertex by averaging normals of connected triangles. If set to False (default) then normals from the .obj file are used or precalculated normals are not used (normals are calculated from the mesh triangles during ray tracing).

NpOptiX.load_merged_mesh_obj(file_name: str, mesh_name: str, c: Any = array([0.94, 0.94, 0.94], dtype=float32), mat: str = 'diffuse', make_normals: bool = False) → None[source]

Load and merge mesh geometries from Wavefront .obj file.

All objects are imported from file and merged in a single PlotOptiX mesh. This method can read files with no named objects specified.

Parameters
  • file_name (string) – File name (local file path or url) to read from.

  • mesh_name (string) – Name of the new mesh geometry.

  • c (Any, optional) – Color of the mesh. Single value means a constant gray level. 3-component array means constant RGB color.

  • mat (string, optional) – Material name.

  • make_normals (bool, optional) – If set to True and .obj file does not contain normals then normals are calculated for each vertex by averaging normals of connected triangles. If set to False (default) then normals from the .obj file are used or precalculated normals are not used (normals are calculated from the mesh triangles during ray tracing).

NpOptiX.set_displacement(name: str, data: Any, addr_mode: Union[plotoptix.enums.TextureAddressMode, str] = <TextureAddressMode.Wrap: 0>, keep_on_host: bool = False, refresh: bool = False) → None[source]

Set surface displacement data.

Set displacement data for the object name. Geometry attribute program of the object has to be set to plotoptix.enums.GeomAttributeProgram.DisplacedSurface. The data has to be a 2D array containing displacement map.

Use keep_on_host=True to make a copy of data in the host memory (in addition to GPU memory), this option is required when (small) arrays are going to be saved to JSON description of the scene.

Parameters
  • name (string) – Object name.

  • data (array_like) – Displacement map data.

  • addr_mode (TextureAddressMode or string, optional) – Texture addressing mode on edge crossing.

  • keep_on_host (bool, optional) – Store texture data copy in the host memory.

  • refresh (bool, optional) – Set to True if the image should be re-computed.

NpOptiX.load_displacement(name: str, file_name: str, prescale: float = 1.0, baseline: float = 0.0, addr_mode: Union[plotoptix.enums.TextureAddressMode, str] = <TextureAddressMode.Wrap: 0>, refresh: bool = False) → None[source]

Load surface displacement data from file.

Load displacement data for the object name from an image file. Geometry attribute program of the object has to be set to plotoptix.enums.GeomAttributeProgram.DisplacedSurface. Tilt data is stored in the device memory only (there is no host copy).

Parameters
  • name (string) – Object name.

  • file_name (string) – Image file name with the displacement data.

  • prescale (float, optional) – Scaling factor for displacement values.

  • baseline (float, optional) – Baseline added to displacement values.

  • addr_mode (TextureAddressMode or string, optional) – Texture addressing mode on edge crossing.

  • refresh (bool, optional) – Set to True if the image should be re-computed.

NpOptiX.delete_geometry(name: str) → None[source]

Remove geometry from the scene.

Parameters

name (string) – Name of the geometry.

Direct modifications of data

These methods allow making changes to properties of data points stored internally in the raytracer, without re-sending whole data arrays from the Python code.

plotoptix.geometry.PinnedBuffer functionality should be considered experimental, although it seems to be extremely useful in simulation use cases.

class plotoptix.geometry.PinnedBuffer(geom: plotoptix.geometry.GeometryMeta, buffer: plotoptix.enums.GeomBuffer)[source]

Pins an internal buffer memory and exposes it as an np.ndarray.

Use only within the with block as in the provided example. The exposed array is not going out of scope nor is anyhow protected outside that expression due to the current limitations of the array interface; be careful and do not use the array outside with as memory can be reallocated.

Parameters
  • geom (GeometryMeta) – Geometry metadata for the object, available in plotoptix.NpOptiX.geometry_data dictionary.

  • buffer (GeomBuffer or string) – Buffer kind to pin.

Returns

out – Buffer data wrapped in np.ndarray.

Return type

ndarray

Examples

>>> rt = NpOptiX()
>>> rt.set_data("plot", xyz=np.random.random((100, 3)), r=0.05)
>>>
>>> with PinnedBuffer(rt.geometry_data["plot"], "Positions") as b:
>>>     print("internal data:", b.shape)
>>>     print("b[:3])
>>>
>>>     b *= 1.5
>>>     rt.update_geom_buffers("plot", "Positions", forced=True)
NpOptiX.move_geometry(name: str, v: Tuple[float, float, float], update: bool = True) → None[source]

Move all primitives by (x, y, z) vector.

Updates GPU buffers immediately if update is set to True (default), otherwise update should be made using plotoptix.NpOptiX.update_geom_buffers() after all geometry modifications are finished.

Parameters
  • name (string) – Name of the geometry.

  • v (tuple (float, float, float)) – (X, Y, Z) shift.

  • update (bool, optional) – Update GPU buffer.

NpOptiX.move_primitive(name: str, idx: int, v: Tuple[float, float, float], update: bool = True) → None[source]

Move selected primitive by (x, y, z) vector.

Updates GPU buffers immediately if update is set to True (default), otherwise update should be made using plotoptix.NpOptiX.update_geom_buffers() after all geometry modifications are finished.

Parameters
  • name (string) – Name of the geometry.

  • idx (int) – Primitive index.

  • v (tuple (float, float, float)) – (X, Y, Z) shift.

  • update (bool, optional) – Update GPU buffer.

NpOptiX.rotate_geometry(name: str, rot: Tuple[float, float, float], center: Optional[Tuple[float, float, float]] = None, update: bool = True) → None[source]

Rotate all primitives by specified degrees.

Rotate all primitives by specified degrees around x, y, z axis, with respect to the center of the geometry. Update GPU buffers immediately if update is set to True (default), otherwise update should be made using plotoptix.NpOptiX.update_geom_buffers() after all geometry modifications are finished.

Parameters
  • name (string) – Name of the geometry.

  • rot (tuple (float, float, float)) – Rotation around (X, Y, Z) axis.

  • center (tuple (float, float, float), optional) – Rotation center. If not provided, rotation is made about the geometry center.

  • update (bool, optional) – Update GPU buffer.

NpOptiX.rotate_primitive(name: str, idx: int, rot: Tuple[float, float, float], center: Optional[Tuple[float, float, float]] = None, update: bool = True) → None[source]

Rotate selected primitive by specified degrees.

Rotate selected primitive by specified degrees around x, y, z axis, with respect to the center of the selected primitive. Update GPU buffers immediately if update is set to True (default), otherwise update should be made using plotoptix.NpOptiX.update_geom_buffers() after all geometry modifications are finished.

Parameters
  • name (string) – Name of the geometry.

  • idx (int) – Primitive index.

  • rot (tuple (float, float, float)) – Rotation around (X, Y, Z) axis.

  • center (tuple (float, float, float), optional) – Rotation center. If not provided, rotation is made about the primitive center.

  • update (bool, optional) – Update GPU buffer.

NpOptiX.scale_geometry(name: str, s: Union[float, Tuple[float, float, float]], center: Optional[Tuple[float, float, float]] = None, update: bool = True) → None[source]

Scale all primitive’s positions and sizes.

Scale all primitive’s positions and sizes by specified factor, with respect to the center of the geometry. Update GPU buffers immediately if update is set to True (default), otherwise update should be made using plotoptix.NpOptiX.update_geom_buffers() after all geometry modifications are finished.

Parameters
  • name (string) – Name of the geometry.

  • s (float, tuple (float, float, float)) – Scaling factor, single value or (x, y, z) scales.

  • center (tuple (float, float, float), optional) – Scaling center. If not provided, scaling is made w.r.t. the primitive center.

  • update (bool, optional) – Update GPU buffer.

NpOptiX.scale_primitive(name: str, idx: int, s: Union[float, Tuple[float, float, float]], center: Optional[Tuple[float, float, float]] = None, update: bool = True) → None[source]

Scale selected primitive.

Scale selected primitive by specified factor, with respect to the center of the selected primitive. Update GPU buffers immediately if update is set to True (default), otherwise update should be made using plotoptix.NpOptiX.update_geom_buffers() after all geometry modifications are finished.

Parameters
  • name (string) – Name of the geometry.

  • idx (int) – Primitive index.

  • s (float, tuple (float, float, float)) – Scaling factor, single value or (x, y, z) scales.

  • center (tuple (float, float, float), optional) – Scaling center. If not provided, scaling is made w.r.t. the primitive center.

  • update (bool, optional) – Update GPU buffer.

NpOptiX.update_geom_buffers(name: str, mask: Union[plotoptix.enums.GeomBuffer, str] = <GeomBuffer.All: 4294967295>, forced: bool = False) → None[source]

Update geometry buffers.

Update geometry buffers in GPU after modifications made with plotoptix.NpOptiX.move_geometry(), plotoptix.NpOptiX.move_primitive(), and similar methods.

Parameters
  • name (string) – Name of the geometry.

  • mask (GeomBuffer or string, optional) – Which buffers to update. All buffers if not specified.

  • forced (bool, optional) – Update even if the object was not tagged as outdated. Operations like rotations, scaling, shifts, are setting “out of date” flag, but direct modifications of buffers memory performed with plotoptix.geometry.PinnedBuffer require forced update.

Coordinate system

Note: coordinate system layouts are now under development, only a simple box containing all data is available now.

NpOptiX.set_coordinates(mode: Union[plotoptix.enums.Coordinates, str] = <Coordinates.Box: 1>, thickness: float = 1.0) → None[source]

Set style of the coordinate system geometry (or hide it).

Parameters
  • mode (Coordinates enum or string, optional) – Style of the coordinate system geometry.

  • thickness (float, optional) – Thickness of lines.