scimesh Namespace Reference

Namespaces
namespace	detail
	Internal helpers of the text renderer.
namespace	gltf_io
namespace	obj_io
	Functions for reading OBJ files.
namespace	ply_io
	Functions for reading PLY files.
namespace	stl_io
	Functions for reading and writing STL files.

Classes
struct	ApplyColormapResult
	Result of apply_colormap() for a single dataset. More...
struct	Camera
	A virtual camera that defines the viewpoint for rendering. More...
struct	ClipPlane
	A clipping plane that can hide parts of the scene. More...
struct	ClipVertex
	A processed vertex in clip space, ready for perspective divide. More...
struct	Color
	An RGBA color with floating-point components. More...
struct	ColorMap
	Self-contained colormap — owns a colour lookup table and supports linearly interpolated sampling. More...
class	Font
	A TrueType font, loaded at a fixed pixel size, with a glyph cache. More...
struct	FontMetrics
	Vertical metrics of a font at a given pixel size. More...
struct	GlyphBitmap
	One rasterized glyph: an 8-bit coverage bitmap plus placement info. More...
struct	Image
	A 2D RGBA image buffer. More...
struct	Light
	A light source for the Blinn-Phong shading model. More...
struct	LineLayer
	A batch of independent line segments drawn with a fixed screen-space width. More...
struct	LineNodeRef
	A non-owning reference to one line layer in a scene, together with its placement transform (and optional name). More...
struct	Mesh
	A 3D triangle mesh using an indexed face set representation. More...
struct	MultiApplyColormapResult
	Aggregate result of apply_colormap() for multiple datasets. More...
struct	ProjectedPoint
	A world-space point projected into the rendered image. More...
struct	Rasterizer
	Low-level triangle rasterizer with depth buffering and lighting. More...
class	Renderer
	The main rendering engine. More...
struct	RenderOptions
	All settings that control rendering output. More...
struct	Scene
	A collection of Mesh objects to be rendered together. More...
struct	SceneNodeRef
	A lightweight, non-owning reference to one mesh in a scene, together with its placement transform (and optional name). More...
struct	TextDrawStyle
	How to draw text onto an image with draw_text(). More...
struct	TextExtent
	Size of a (possibly multi-line) piece of text. More...
struct	TextLayer
	A batch of text labels drawn together, in one coordinate space. More...
struct	TextNodeRef
	A non-owning reference to one text layer in a scene, together with its placement transform (and optional name). More...
struct	Triangle
	A triangle defined by three vertex indices. More...
struct	ViewClipVertex

Typedefs
using	Vec2 = glm::vec2
	2-component floating-point vector (xy).
using	Vec3 = glm::vec3
	3-component floating-point vector (xyz).
using	Vec4 = glm::vec4
	4-component floating-point vector (xyzw).
using	Mat4 = glm::mat4
	4×4 floating-point matrix.

Enumerations
enum class	ProjectionType { ORTHOGRAPHIC , PERSPECTIVE }
	The type of 3D→2D projection used by the camera. More...
enum class	MergeDirection { LEFT , RIGHT , TOP , BOTTOM }
	Direction for the merge() operation. More...
enum class	CropContentDirection {   LEFT , RIGHT , HORIZONTAL , TOP ,   BOTTOM , VERTICAL , ALL }
	Direction(s) for the crop_to_content() operation. More...
enum class	FitMode { PAD , SCALE }
	Strategy for normalizing images to a common cell size in grid_arrange(). More...
enum class	ShadingMode { SMOOTH , FLAT }
	How surface normals are interpolated across triangles. More...
enum class	TextSpace { WORLD , SCREEN }
	The coordinate space of a TextLayer's positions. More...
enum class	PlaneSpace { WORLD , EYE }
	Coordinate space in which a ClipPlane is defined. More...
enum class	FogSpace { WORLD , NDC }
	Coordinate space (and hence the unit) of the fog distances RenderOptions::fog_start and RenderOptions::fog_end. More...

Functions
ProjectedPoint	world_to_screen (const Camera &camera, const Vec3 &world, int width, int height, ProjectionType projection, float near_plane, float far_plane)
	Project a world-space point to the pixel coordinates of a rendered image.
Camera	camera_look_at (const Vec3 &center, float radius, const Vec3 &direction, const Vec3 &up, float fov_degrees, float margin=1.1f, ProjectionType projection=ProjectionType::PERSPECTIVE)
	Create a camera that looks at a point from a given distance and direction.
Camera	camera_fit_scene (const Scene &scene, const Vec3 &direction, const Vec3 &up, float fov_degrees, float margin=1.1f, ProjectionType projection=ProjectionType::PERSPECTIVE)
	Create a camera that automatically frames an entire Scene.
Camera	camera_fit_mesh (const Mesh &mesh, const Vec3 &direction, const Vec3 &up, float fov_degrees, float margin=1.1f, ProjectionType projection=ProjectionType::PERSPECTIVE)
	Create a camera that automatically frames a single Mesh.
Camera	camera_orbit (const Camera &camera, const Vec3 &axis, float angle_degrees)
	Orbit the camera around its look-at point.
int	clip_triangle_near_plane (const ClipVertex &v0, const ClipVertex &v1, const ClipVertex &v2, std::vector< ClipVertex > &output_vertices, std::vector< Triangle > &output_triangles)
	Clip a triangle against the near clipping plane in clip space.
int	clip_triangle_view_plane (const Vec3 &v0, const Vec3 &v1, const Vec3 &v2, const Vec3 &n0, const Vec3 &n1, const Vec3 &n2, const Color &c0, const Color &c1, const Color &c2, const Vec2 &uv0, const Vec2 &uv1, const Vec2 &uv2, const ClipPlane &plane, std::vector< ClipVertex > &output_vertices, std::vector< Triangle > &output_triangles)
	Clip a triangle against an arbitrary plane in view space.
ApplyColormapResult	apply_colormap (const std::vector< float > &data, const ColorMap &colormap, float vmin=NAN, float vmax=NAN, const Color &nan_color=Color{0.5f, 0.5f, 0.5f, 1.0f}, float lo_pct=0.0f, float hi_pct=100.0f)
	Map a single vector of numeric data to RGBA colours using a colormap.
MultiApplyColormapResult	apply_colormap (const std::vector< std::vector< float > > &datasets, const ColorMap &colormap, float vmin=NAN, float vmax=NAN, const Color &nan_color=Color{0.5f, 0.5f, 0.5f, 1.0f}, float lo_pct=0.0f, float hi_pct=100.0f, bool global_range=false)
	Map multiple vectors of numeric data through a single colormap.
std::string	default_font_path ()
	Path of the bundled default font, or as overridden by the SCIMESH_FONT environment variable.
std::string	resolve_font_path (const std::string &path)
	Turn a possibly empty font path into a path that exists.
Font	cached_font (const std::string &path, float pixel_size)
	Load a font, re-using an already loaded one when possible.
void	clear_font_cache ()
	Drop all fonts from the process-wide font cache.
Image	grid_arrange (const std::vector< Image > &images, int ncol=0, int nrow=0, FitMode fit_mode=FitMode::PAD, const Color &background=Color(1.0f, 1.0f, 1.0f, 1.0f))
	Arrange a list of images into a grid layout.
void	compute_vertex_normals (const Mesh &mesh, std::vector< Vec3 > &normals)
	Compute per-vertex normals by averaging adjacent face normals.
Mesh	generate_sphere (const Vec3 &center, float radius, int segments, const Color &color)
	Generate a UV-sphere (latitude/longitude tessellation).
Mesh	generate_cylinder (const Vec3 &start, const Vec3 &end, float radius, int segments, const Color &color, bool caps=true)
	Generate a cylinder between two endpoints.
Mesh	generate_cone (const Vec3 &base, const Vec3 &tip, float radius, int segments, const Color &color)
	Generate a cone from a base circle to a tip point.
Mesh	generate_arrow (const Vec3 &from, const Vec3 &to, float shaft_radius, float head_radius, float head_length, int segments, const Color &color)
	Generate a 3D arrow from from to to.
void	merge_mesh (Mesh &dst, const Mesh &src)
	Merge one mesh into another (append geometry).
Mesh	generate_multi_spheres (const std::vector< Vec3 > &centers, const std::vector< float > &radii, const std::vector< Color > &colors, int segments=16)
	Generate multiple spheres in a single mesh (efficient batching).
Mesh	generate_multi_cylinders (const std::vector< Vec3 > &starts, const std::vector< Vec3 > &ends, const std::vector< float > &radii, const std::vector< Color > &colors, int segments=12, bool caps=true)
	Generate multiple cylinders in a single mesh (efficient batching).
Mesh	generate_tube (const std::vector< Vec3 > &path, float radius, int segments, const Color &color, bool cap_start=true, bool cap_end=true)
	Generate a tube (generalized cylinder) along a polyline path.
Mesh	generate_multi_tubes (const std::vector< std::vector< Vec3 > > &paths, const std::vector< float > &radii, const std::vector< Color > &colors, int segments=12, bool caps=false)
	Generate multiple tubes in a single mesh (efficient batching).
Mesh	generate_cuboid (const Vec3 &center, const Vec3 &half_extents, const Color &color)
	Generate an axis-aligned cuboid (rectangular box).
Mesh	generate_pyramid (const Vec3 &base_center, const Vec3 &apex, float half_width, const Color &color)
	Generate a square-based pyramid.
Mesh	generate_tetrahedron (const Vec3 &p0, const Vec3 &p1, const Vec3 &p2, const Vec3 &p3, const Color &color)
	Generate a tetrahedron (triangular pyramid) from four points.
Mesh	generate_torus (const Vec3 &center, float major_radius, float minor_radius, int major_segments, int minor_segments, const Color &color)
	Generate a torus (donut shape).
Mesh	generate_plane (const Vec3 &center, const Vec3 &normal, float half_size_x, float half_size_y, const Color &color)
	Generate a flat rectangular plane.
void	draw_text (Image &image, const std::string &text, const Font &font, float x, float baseline_y, const TextDrawStyle &style=TextDrawStyle())
	Draw text into an image at a given position and baseline.
TextExtent	measure_text (const std::string &text, float size, const std::string &font_file="", float line_spacing=1.2f)
	Measure a (possibly multi-line) string in a given font and size.
void	translate_mesh (Mesh &mesh, const Vec3 &translation)
	Translate (move) a mesh by a displacement vector.
void	scale_mesh (Mesh &mesh, const Vec3 &scale)
	Scale a mesh non-uniformly along each axis.
void	scale_mesh (Mesh &mesh, float uniform_scale)
	Scale a mesh uniformly in all directions.
void	rotate_mesh (Mesh &mesh, float angle_radians, const Vec3 &axis)
	Rotate a mesh around an arbitrary axis.
void	transform_mesh (Mesh &mesh, const Mat4 &matrix)
	Apply an arbitrary 4×4 transformation matrix to a mesh.
Mesh	mesh_from_fs (const std::vector< float > &fs_vertices, const std::vector< uint32_t > &fs_faces, const std::vector< float > &per_vertex_values={}, const std::vector< uint8_t > &rgb_bytes={}, bool detect_transparency=false)
	Convert a FreeSurfer-format mesh (flat vertex/face arrays) to a scimesh Mesh.
void	flip_uvs (Mesh &mesh)
	Flip the texture coordinates of a mesh vertically (v → 1 − v).
float	perp_extent_radius (const Vec3 &bmin, const Vec3 &bmax, const Vec3 &center, const Vec3 &dir, float fov_radians, float *out_dist=nullptr)
	Compute the "perpendicular extent radius" of an axis-aligned bounding box relative to a view direction.
float	max_ortho_extent (const Vec3 &bmin, const Vec3 &bmax, const Vec3 &center, const Vec3 &dir)
	Compute the maximum perpendicular extent of an AABB from a view ray (for orthographic projection framing).
ClipPlane	clip_plane_to_view_space (const ClipPlane &plane, const Vec3 &eye, const Mat4 &view)
	Convert a ClipPlane to view (eye) space, ready for clipping.
Mesh	convert_fs_mesh (const fs::Mesh &fs_mesh)
	Convert a FreeSurfer mesh to a scimesh Mesh (no colors).
Mesh	convert_fs_mesh (const fs::Mesh &fs_mesh, const Color &solid_color)
	Convert a FreeSurfer mesh to a scimesh Mesh with a solid color.
Mesh	convert_fs_mesh (const fs::Mesh &fs_mesh, const std::vector< uint8_t > &rgb_colors)
	Convert a FreeSurfer mesh with per-vertex RGB coloring.
Mesh	convert_fs_mesh (const fs::Mesh &fs_mesh, const std::vector< float > &morph_data, const std::vector< uint8_t > &rgb_colors, float nan_alpha=1.0f)
	Convert a FreeSurfer mesh with per-vertex morphological data and RGB coloring.
Image	stack_horizontal (const std::vector< Image > &images, FitMode fit_mode=FitMode::PAD, const Color &background=Color(1.0f, 1.0f, 1.0f, 1.0f))
	Stack images horizontally in a single row.
Image	stack_vertical (const std::vector< Image > &images, FitMode fit_mode=FitMode::PAD, const Color &background=Color(1.0f, 1.0f, 1.0f, 1.0f))
	Stack images vertically in a single column.
Vec3	compute_face_normal (const Vec3 &v0, const Vec3 &v1, const Vec3 &v2)
	Compute the unit-length normal vector of a triangle face.
Vec3	transform_point (const Mat4 &m, const Vec3 &p)
	Transform a point by a 4×4 matrix (with implicit w=1).
Vec4	transform_point_homogeneous (const Mat4 &m, const Vec3 &p)
	Transform a point by a 4×4 matrix, returning the full Vec4 result.
Vec3	transform_direction (const Mat4 &m, const Vec3 &d)
	Transform a direction vector by a 4×4 matrix (with implicit w=0).
Vec3	perspective_divide (const Vec4 &clip)
	Perform perspective division: divide xyz by w.
void	ndc_to_screen (const Vec3 &ndc, int width, int height, float &screen_x, float &screen_y, float &depth)
	Convert from normalized device coordinates (NDC) to screen (pixel) coordinates.
void	compute_barycentric (float px, float py, float x0, float y0, float x1, float y1, float x2, float y2, float &u, float &v, float &w)
	Compute barycentric coordinates (u, v, w) of a point in a triangle.
Color	shade_pixel (const Color &base_color, const Vec3 &normal, const Vec3 &light_direction, const Color &specular_color=Color(0, 0, 0, 0), float shininess=0.0f)
	Compute the shaded color of a pixel with a single directional light.
Color	shade_pixel_multi (const Color &base_color, const Vec3 &normal, const std::vector< Light > &lights, float ambient, const Color &specular_color=Color(0, 0, 0, 0), float shininess=0.0f)
	Compute the shaded color with multiple light sources.
float	path_length (const std::vector< Vec3 > &path, bool closed=false)
	Total length of a polyline path.
std::vector< Vec3 >	remove_duplicate_points (const std::vector< Vec3 > &path, float epsilon=1e-6f)
	Remove points that repeat their predecessor.
std::vector< Vec3 >	path_tangents (const std::vector< Vec3 > &path, bool closed=false)
	Unit tangent direction at every point of a path.
std::vector< float >	path_curvature (const std::vector< Vec3 > &path, bool closed=false)
	Discrete curvature at every point of a path.
std::vector< Vec3 >	resample_by_arclength (const std::vector< Vec3 > &path, float step, bool closed=false)
	Resample a path at a fixed arc-length step.
std::vector< Vec3 >	hermite_path (const std::vector< Vec3 > &points, const std::vector< Vec3 > &tangents, int samples_per_segment=8, bool closed=false)
	Sample a cubic Hermite curve with caller-supplied tangents.
std::vector< Vec3 >	catmull_rom_path (const std::vector< Vec3 > &points, int samples_per_segment=8, bool closed=false, float alpha=0.5f)
	Sample a non-uniform Catmull-Rom curve through the given points.
std::vector< Vec3 >	bspline_path (const std::vector< Vec3 > &points, int samples_per_segment=8, bool closed=false)
	Sample a uniform cubic B-spline through the given points.
std::vector< Vec3 >	bezier_path (const std::vector< Vec3 > &control_points, int samples=64)
	Sample a Bezier curve from a control polygon.
const char *	str_projection (ProjectionType p)
const char *	str_shading (ShadingMode s)
const char *	str_plane_space (PlaneSpace s)
const char *	str_fog_space (FogSpace s)
const char *	str_merge (MergeDirection d)
const char *	str_crop (CropContentDirection d)
std::string	fmt_count (size_t n)
std::string	fmt_size_bytes (size_t bytes)
std::ostream &	operator<< (std::ostream &os, const Color &c)
std::ostream &	operator<< (std::ostream &os, const Vec3 &v)
std::ostream &	operator<< (std::ostream &os, const Triangle &t)
std::ostream &	operator<< (std::ostream &os, ShadingMode s)
std::ostream &	operator<< (std::ostream &os, ProjectionType p)
std::ostream &	operator<< (std::ostream &os, const Light &l)
std::ostream &	operator<< (std::ostream &os, const ClipPlane &cp)
std::ostream &	operator<< (std::ostream &os, const Camera &cam)
std::ostream &	operator<< (std::ostream &os, const Mesh &m)
std::ostream &	operator<< (std::ostream &os, const Scene &s)
std::ostream &	operator<< (std::ostream &os, const Image &img)
std::ostream &	operator<< (std::ostream &os, const RenderOptions &opts)

Variables
constexpr Color	DEFAULT_COLOR {0.7f, 0.7f, 0.7f, 1.0f}
	The default mesh color: a neutral light gray (0.7, 0.7, 0.7).
constexpr Color	TRANSPARENT_BLACK {0.0f, 0.0f, 0.0f, 0.0f}
	A fully transparent black color (0, 0, 0, 0).
constexpr Color	WHITE {1.0f, 1.0f, 1.0f, 1.0f}
	An opaque white color (1, 1, 1, 1).

Typedef Documentation

Mat4

using scimesh::Mat4 = typedef glm::mat4

4×4 floating-point matrix.

Used for model, view, and projection transforms. GLM matrices are column-major, matching OpenGL conventions.

Example

Mat4 identity(1.0f);                   // identity matrix
Mat4 scaled = glm::scale(identity, Vec3(2.0f));  // scale by 2

See also

Vec3, Vec4

Definition at line 65 of file types.h.

Vec2

using scimesh::Vec2 = typedef glm::vec2

2-component floating-point vector (xy).

Use v.x, v.y to access components.

See also

Vec3, Vec4, Mat4

Definition at line 32 of file types.h.

Vec3

using scimesh::Vec3 = typedef glm::vec3

3-component floating-point vector (xyz).

This is the workhorse type for positions, directions, and normals. Access components with .x, .y, .z.

Example

Vec3 pos(1.0f, 2.0f, 3.0f);   // a point in 3D space
Vec3 dir = glm::normalize(pos); // convert to unit-length direction
float dot = glm::dot(pos, dir); // dot product

See also

Vec2, Vec4, Mat4

Definition at line 46 of file types.h.

Vec4

using scimesh::Vec4 = typedef glm::vec4

4-component floating-point vector (xyzw).

Primarily used internally for homogeneous clip-space coordinates.

See also

Vec3, Mat4

Definition at line 52 of file types.h.

Enumeration Type Documentation

CropContentDirection

enum class scimesh::CropContentDirection

strong

Direction(s) for the crop_to_content() operation.

Specifies which edges to crop. You can crop individual edges or combinations.

See also

Image::crop_to_content()

Enumerator
LEFT	Crop left edge only.
RIGHT	Crop right edge only.
HORIZONTAL	Crop both left and right edges.
TOP	Crop top edge only.
BOTTOM	Crop bottom edge only.
VERTICAL	Crop both top and bottom edges.
ALL	Crop all four edges.

Definition at line 38 of file image.h.

FitMode

enum class scimesh::FitMode

strong

Strategy for normalizing images to a common cell size in grid_arrange().

See also

grid_arrange()

Enumerator
PAD	Pad smaller images with background color (content stays pixel-perfect).
SCALE	Scale all images to match the largest cell dimensions.

Definition at line 51 of file image.h.

FogSpace

enum class scimesh::FogSpace

strong

Coordinate space (and hence the unit) of the fog distances RenderOptions::fog_start and RenderOptions::fog_end.

See also

RenderOptions::fog_space, RenderOptions::fog_start

Enumerator
WORLD	World units: distance from the camera, measured along the camera's viewing direction. fog_start = 10 means "fog begins 10 world units in front of the camera". This is the default; it is independent of the near/far plane settings and of the projection type, and does not change when the camera is moved within the scene.
NDC	Normalized device depth: the raw values of the depth buffer, in [-1, 1], where -1 is the near plane, 0 the middle of the depth range and +1 the far plane. This is the legacy behaviour; it depends on RenderOptions::near_plane / RenderOptions::far_plane and (for perspective projections) is strongly non-linear in world units.

Definition at line 297 of file types.h.

MergeDirection

enum class scimesh::MergeDirection

strong

Direction for the merge() operation.

Controls which side of the base image the other image is attached to.

See also

Image::merge()

Enumerator
LEFT	Attach other to the left side.
RIGHT	Attach other to the right side.
TOP	Attach other above.
BOTTOM	Attach other below.

Definition at line 26 of file image.h.

PlaneSpace

enum class scimesh::PlaneSpace

strong

Coordinate space in which a ClipPlane is defined.

See also

ClipPlane::space, ClipPlane

Enumerator
WORLD	World (scene) space: the plane is fixed in the scene, so it does not move when the camera moves. This is the default, and matches the convention of rgl (clipplanes3d), VTK/PyVista, ParaView and three.js.
EYE	Eye (view/camera) space: the plane is anchored to the camera and therefore travels and rotates with it. This matches the classic OpenGL glClipPlane behaviour and is handy for camera-attached cutaways (e.g. "always cut away everything close to the viewer").

Definition at line 210 of file types.h.

ProjectionType

enum class scimesh::ProjectionType

strong

The type of 3D→2D projection used by the camera.

See also

Camera, Camera::projection

Enumerator
ORTHOGRAPHIC	Orthographic projection: parallel lines stay parallel. Objects do not get smaller with distance. Useful for technical diagrams, architectural plans, and when you need to preserve relative sizes regardless of depth.
PERSPECTIVE	Perspective projection: objects farther away appear smaller. This mimics how the human eye and real cameras work. The field of view (FOV) controls how "wide" the lens is. This is the default.

Definition at line 23 of file camera.h.

ShadingMode

enum class scimesh::ShadingMode

strong

How surface normals are interpolated across triangles.

See also

RenderOptions::shading

Enumerator
SMOOTH	Smooth (Gouraud) shading: normals are interpolated across each triangle, producing a smooth, rounded appearance. Best for curved surfaces like spheres. Requires per-vertex normals (use compute_vertex_normals() to generate them).
FLAT	Flat shading: each triangle uses a single normal, giving a faceted, low-poly look. Best for mechanical parts, cubes, or when you want to emphasize the mesh structure.

Definition at line 22 of file render_options.h.

TextSpace

enum class scimesh::TextSpace

strong

The coordinate space of a TextLayer's positions.

See also

TextLayer::space

Enumerator
WORLD	3D world coordinates, projected with the scene camera. Use this for labels that belong to a location in the scene: the label follows the annotated point when the camera moves, and it can be hidden by geometry in front of it (see TextLayer::depth_test).
SCREEN	Output image pixels, origin at the top left, y growing down. Use this for labels whose place is defined by the figure layout rather than by the 3D scene (titles, panel tags, corner annotations). The values are in the pixels of the final image, independent of the anti-aliasing factor.

Definition at line 50 of file text.h.

Function Documentation

apply_colormap() [1/2]

ApplyColormapResult scimesh::apply_colormap	(	const std::vector< float > &	data,
		const ColorMap &	colormap,
		float	vmin = NAN,
		float	vmax = NAN,
		const Color &	nan_color = Color{0.5f, 0.5f, 0.5f, 1.0f},
		float	lo_pct = 0.0f,
		float	hi_pct = 100.0f
	)

Map a single vector of numeric data to RGBA colours using a colormap.

Each element of data is normalised to [0, 1] based on the effective data range and then mapped through the colormap. NaN / Inf values receive nan_color.

Parameters

data	Per-vertex (or per-element) numeric values. NaN / Inf allowed — they will be mapped to nan_color.
colormap	The colour lookup table to sample from.
vmin	Lower bound of the data range. NAN = auto-detect from finite values (after winsorizing, if applicable).
vmax	Upper bound of the data range. NAN = auto-detect.
nan_color	RGBA colour for NaN / Inf positions.
lo_pct	Lower percentile for winsorizing (0.0 = off). E.g., 2.0 → clip values below the 2nd percentile.
hi_pct	Upper percentile for winsorizing (100.0 = off). E.g., 98.0 → clip values above the 98th percentile.

Returns

An ApplyColormapResult with the mapped colours and metadata.

Example — single dataset with winsorizing

std::vector<float> data = {1.2f, 3.4f, NAN, 2.1f, 99.0f, 2.8f};
ColorMap cmap = build_viridis();  // user-supplied 256-entry colormap
 
auto r = apply_colormap(data, cmap, NAN, NAN,
                         Color(1,1,1,1),  // white NaN
                         5.0f, 95.0f);    // clip 5th/95th percentiles
 
// r.colors[i]      — colour for data[i]
// r.data_min/max   — effective range (after winsorizing) → use for colourbar
// r.winsor_lo/hi   — the actual percentile cutoff values

Definition at line 345 of file colormap.cpp.

apply_colormap() [2/2]

MultiApplyColormapResult scimesh::apply_colormap	(	const std::vector< std::vector< float > > &	datasets,
		const ColorMap &	colormap,
		float	vmin = NAN,
		float	vmax = NAN,
		const Color &	nan_color = Color{0.5f, 0.5f, 0.5f, 1.0f},
		float	lo_pct = 0.0f,
		float	hi_pct = 100.0f,
		bool	global_range = false
	)

Map multiple vectors of numeric data through a single colormap.

This is the multi-dataset overload. Each dataset (e.g., per-vertex data for the left and right brain hemispheres) is mapped independently, and pooled statistics across all datasets are always computed.

Parameters

datasets	One or more per-vertex (or per-element) data vectors.
colormap	The colour lookup table.
vmin	Lower bound. NAN = auto-detect.
vmax	Upper bound. NAN = auto-detect.
nan_color	RGBA colour for NaN / Inf positions.
lo_pct	Lower percentile for winsorizing (0.0 = off).
hi_pct	Upper percentile for winsorizing (100.0 = off).
global_range	If true, compute vmin/vmax from all datasets pooled together, so both hemispheres use the same colour scale. If false, each dataset gets its own independent range (unless vmin/vmax are explicitly set, which overrides everything).

Returns

A MultiApplyColormapResult with per-dataset colours and pooled metadata.

Example — two hemispheres, shared colour scale

std::vector<float> lh_thickness = {2.3f, 2.1f, NAN, ...};
std::vector<float> rh_thickness = {2.5f, 2.0f, NAN, ...};
 
auto r = apply_colormap({lh_thickness, rh_thickness}, cmap,
                         NAN, NAN,
                         Color(1,1,1,1),  // white NaN (medial wall)
                         2.0f, 98.0f,     // clip outliers
                         true);            // shared range
 
// r.per_dataset[0].colors  — colours for left hemisphere
// r.per_dataset[1].colors  — colours for right hemisphere
// r.pooled_data_min/max    — shared range → use for colourbar

Definition at line 397 of file colormap.cpp.

bezier_path()

std::vector< Vec3 > scimesh::bezier_path ( const std::vector< Vec3 > &  control_points, int  samples = 64  )

inline

Sample a Bezier curve from a control polygon.

Evaluates the Bernstein form of the curve by de Casteljau's algorithm, which is numerically stable for any number of control points (unlike summing the Bernstein polynomials explicitly). Unlike the Catmull-Rom and B-spline functions, the control points are not points on the curve: only the first and last one are, and the rest pull it like a magnet. This is the function to use when your input really is a Bezier control polygon (a font outline, a vector-graphics path, a designed shape).

Parameters

control_points	Control polygon (at least 2 points).
samples	Number of points to emit along the curve (at least 2; the samples include both endpoints).

Returns

The sampled path, or an empty vector if there are not enough control points.

Example

// A quadratic Bezier arc, drawn as a tube:
std::vector<Vec3> arc = bezier_path({{0,0,0}, {1,1,0}, {2,0,0}}, 64);
Mesh tube = generate_tube(arc, 0.05f, 10, Color(0.2f, 0.6f, 0.9f));

See also

catmull_rom_path()

Definition at line 697 of file spline.h.

bspline_path()

std::vector< Vec3 > scimesh::bspline_path ( const std::vector< Vec3 > &  points, int  samples_per_segment = 8, bool  closed = false  )

inline

Sample a uniform cubic B-spline through the given points.

The approximating counterpart of catmull_rom_path(): the curve is smoother (C2 continuous everywhere, including at the joints) because it does not have to pass through the control points, which it treats as a convex-hull cage it stays inside. Use it when the input points are noisy and you want the curve to iron out the noise rather than reproduce it, or when you want the guaranteed smoothness of a single polynomial piece instead of a chain of cubics.

Note the consequence: the sampled path generally does not contain the input points, and an open curve starts and ends inside the first and last segment instead of at the first and last point. Use catmull_rom_path() when the waypoints are meaningful positions that the curve has to hit.

Parameters

points	Control points (at least 4).
samples_per_segment	Samples per segment (clamped to at least 1).
closed	Whether the curve loops back to its first point.

Returns

The sampled path, or an empty vector if there are fewer than four distinct control points.

Example

// A smoothed (noise-reduced) loop drawn as a tube:
std::vector<Vec3> path = bspline_path(noisy_points, 8, true);
Mesh ring = generate_tube(path, 0.05f, 10, Color(0.9f, 0.9f, 0.2f));

See also

catmull_rom_path()

Definition at line 614 of file spline.h.

cached_font()

Font scimesh::cached_font	(	const std::string &	path,
		float	pixel_size
	)

Load a font, re-using an already loaded one when possible.

Parameters

path	Path to a .ttf file, or an empty string for the bundled default font (see default_font_path()).
pixel_size	Em size in output pixels, must be > 0.

Returns

A handle to the (possibly cached) font.

Exceptions

std::runtime_error

If no font can be found, or it cannot be loaded.

See also

default_font_path(), clear_font_cache()

Definition at line 405 of file font.cpp.

camera_fit_mesh()

Camera scimesh::camera_fit_mesh	(	const Mesh &	mesh,
		const Vec3 &	direction,
		const Vec3 &	up,
		float	fov_degrees,
		float	margin = 1.1f,
		ProjectionType	projection = ProjectionType::PERSPECTIVE
	)

Create a camera that automatically frames a single Mesh.

Convenience wrapper around camera_fit_scene() for the common case of rendering a single mesh.

Parameters

mesh	The mesh to frame.
direction	View direction.
up	Up vector.
fov_degrees	Field of view in degrees.
margin	Extra zoom margin.
projection	Projection type.

Returns

A configured Camera.

Example

Mesh brain = scimesh::obj_io::read_obj("brain.obj");
Camera cam = camera_fit_mesh(brain, {0,0,1}, {0,1,0}, 45.0f);

See also

camera_fit_scene(), camera_look_at()

Definition at line 108 of file camera.cpp.

camera_fit_scene()

Camera scimesh::camera_fit_scene	(	const Scene &	scene,
		const Vec3 &	direction,
		const Vec3 &	up,
		float	fov_degrees,
		float	margin = 1.1f,
		ProjectionType	projection = ProjectionType::PERSPECTIVE
	)

Create a camera that automatically frames an entire Scene.

Computes the combined bounding box of all meshes and sets up the camera to show everything.

Parameters

scene	The scene to frame.
direction	Direction from the scene centre towards the camera, i.e. the side you want to look from (e.g. {0,0,1} for a front view, {-1,0,0} to look at the scene from its -x side).
up	Up vector (e.g. {0,1,0}).
fov_degrees	Field of view in degrees.
margin	Extra zoom margin (default 1.1 = 10% padding).
projection	Projection type (default: PERSPECTIVE).

Returns

A configured Camera.

Example

Scene scene;
scene.meshes.push_back(sphere1);
scene.meshes.push_back(cube1);
Camera cam = camera_fit_scene(scene, {1,1,1}, {0,1,0}, 45.0f);
// camera now frames both objects from a diagonal viewpoint

See also

camera_fit_mesh(), camera_look_at()

Definition at line 91 of file camera.cpp.

camera_look_at()

Camera scimesh::camera_look_at	(	const Vec3 &	center,
		float	radius,
		const Vec3 &	direction,
		const Vec3 &	up,
		float	fov_degrees,
		float	margin = 1.1f,
		ProjectionType	projection = ProjectionType::PERSPECTIVE
	)

Create a camera that looks at a point from a given distance and direction.

This is the low-level function for camera setup. It computes the exact eye position needed to frame a sphere of radius centered at center.

Parameters

center	The point to look at (becomes Camera::center).
radius	The radius of a bounding sphere around the subject.
direction	View direction vector (e.g., {0,0,1} for front view).
up	Up vector (usually {0,1,0}).
fov_degrees	Vertical field of view in degrees.
margin	Extra margin factor (>1.0 = zoomed out, <1.0 = tighter). Default 1.1 gives 10% padding.
projection	Projection type (default: PERSPECTIVE).

Returns

A configured Camera.

Example

Camera cam = camera_look_at({0,0,0}, 5.0f, {0,0,1}, {0,1,0}, 45.0f, 1.2f);
// Looks at origin from +Z, framing a sphere of radius 5, with 20% margin

See also

camera_fit_mesh(), camera_fit_scene()

Definition at line 71 of file camera.cpp.

camera_orbit()

Camera scimesh::camera_orbit	(	const Camera &	camera,
		const Vec3 &	axis,
		float	angle_degrees
	)

Orbit the camera around its look-at point.

Rotates the camera's eye position around camera.center by the given angle around the given axis. The up vector is also rotated.

Parameters

camera	The camera to orbit (modified copy returned).
axis	Rotation axis (should pass through camera.center).
angle_degrees	Rotation angle in degrees.

Returns

A new Camera with the rotated eye position.

Example

Camera cam = camera_fit_mesh(mesh, {0,0,1}, {0,1,0}, 45.0f);
// Rotate 30° around the Y axis (horizontal orbit)
Camera cam2 = camera_orbit(cam, {0,1,0}, 30.0f);

See also

camera_look_at()

Definition at line 125 of file camera.cpp.

catmull_rom_path()

std::vector< Vec3 > scimesh::catmull_rom_path ( const std::vector< Vec3 > &  points, int  samples_per_segment = 8, bool  closed = false, float  alpha = 0.5f  )

inline

Sample a non-uniform Catmull-Rom curve through the given points.

The interpolating spline to use when all you have is a sequence of waypoints and no idea what the tangents should be, which is the usual case: the curve passes through every input point, and each point's tangent is derived from its two neighbours.

alpha selects the parameterization and is the one knob that matters:

• alpha = 0.5 (default) — centripetal. Knot intervals grow with the square root of the chord length, which prevents the cusps, loops and self-intersections that uniform Catmull-Rom produces when the spacing of the input points is uneven (long segment followed by a short one, the norm for measured data — atom traces, streamlines, digitized paths).
• alpha = 1 — chord length: still free of cusps, but can overshoot more.
• alpha = 0 — uniform: the textbook curve, which is exact on evenly spaced points and misbehaves on everything else.

The first and last point of an open curve get a reflected phantom neighbour (2*P0 - P1, 2*Pn - Pn-1), so the curve starts and ends exactly at the given points with a tangent along the first/last segment. Interior points are interpolated with C1 continuity: the tangent is shared by both adjacent segments, so the joint is smooth but not necessarily curvature continuous.

Parameters

points	Points the curve has to pass through (at least 2; at least 3 for a closed curve).
samples_per_segment	Samples per segment (clamped to at least 1).
closed	Whether the curve loops back to its first point.
alpha	Parameterization exponent (see above).

Returns

The sampled path, or an empty vector if there are not enough distinct points.

Example

std::vector<Vec3> waypoints = {{0,0,0}, {1,1,0}, {2,0,0}, {3,1,0}};
std::vector<Vec3> smooth = catmull_rom_path(waypoints, 8);
Mesh tube = generate_tube(smooth, 0.1f, 12, Color(0.8f, 0.2f, 0.2f));

See also

hermite_path(), bspline_path(), generate_tube()

Definition at line 499 of file spline.h.

clear_font_cache()

void scimesh::clear_font_cache

(

)

Drop all fonts from the process-wide font cache.

Fonts in use stay valid (they are reference counted); only the cache is emptied. Mostly useful for tests and for releasing memory in long-running sessions.

Definition at line 428 of file font.cpp.

clip_plane_to_view_space()

ClipPlane scimesh::clip_plane_to_view_space ( const ClipPlane &  plane, const Vec3 &  eye, const Mat4 &  view  )

inline

Convert a ClipPlane to view (eye) space, ready for clipping.

Clipping always happens in view space, so user clip planes have to be converted first. The conversion is a no-op for PlaneSpace::EYE planes (apart from normalizing the normal); for PlaneSpace::WORLD planes (the default) the plane constant is shifted so that the plane stays fixed in world space instead of travelling with the camera:

world: dot(n, p_world) + offset >= 0
       with p_world = R^T * p_view + eye  (view is rigid)
    => dot(R * n, p_view) + (dot(n, eye) + offset) >= 0

The returned plane has a unit-length normal, and its offset is a signed distance in world units; space is copied from the input plane.

A plane with a zero-length normal is neutralized (it is turned into a plane that keeps everything) so that a malformed plane can never blank out a render silently.

Parameters

plane	The clip plane, in world or eye space (see ClipPlane::space).
eye	The camera position in world space (Camera::eye).
view	The world-to-view matrix (Camera::get_view_matrix()).

Returns

The same plane expressed in view space.

Example

Camera cam;
Mat4 view = cam.get_view_matrix();
// World-space cut at x = 0; still cuts at x = 0 in view space.
ClipPlane world_plane{Vec3(-1, 0, 0), 0.0f};
ClipPlane view_plane = clip_plane_to_view_space(world_plane, cam.eye, view);

See also

ClipPlane, PlaneSpace, clip_triangle_view_plane()

Definition at line 85 of file clipping.h.

clip_triangle_near_plane()

int scimesh::clip_triangle_near_plane	(	const ClipVertex &	v0,
		const ClipVertex &	v1,
		const ClipVertex &	v2,
		std::vector< ClipVertex > &	output_vertices,
		std::vector< Triangle > &	output_triangles
	)

Clip a triangle against the near clipping plane in clip space.

This is part of the rendering pipeline — triangles that cross the near plane are split so that only the visible portion (w > 0) is kept.

Parameters

	v0,v1,v2	Three vertices of the input triangle (in homogeneous clip space).
[out]	output_vertices	Clipped vertices are appended here.
[out]	output_triangles	Resulting triangle indices (0, 1, or 2 triangles) are appended here.

Returns

Number of output triangles (0, 1, or 2). 0 means the triangle is entirely behind the near plane and should be discarded.

See also

clip_triangle_view_plane(), Renderer::render_pipeline()

Definition at line 67 of file clipping.cpp.

clip_triangle_view_plane()

int scimesh::clip_triangle_view_plane	(	const Vec3 &	v0,
		const Vec3 &	v1,
		const Vec3 &	v2,
		const Vec3 &	n0,
		const Vec3 &	n1,
		const Vec3 &	n2,
		const Color &	c0,
		const Color &	c1,
		const Color &	c2,
		const Vec2 &	uv0,
		const Vec2 &	uv1,
		const Vec2 &	uv2,
		const ClipPlane &	plane,
		std::vector< ClipVertex > &	output_vertices,
		std::vector< Triangle > &	output_triangles
	)

Clip a triangle against an arbitrary plane in view space.

This is used for user-specified clip planes (see ClipPlane). The plane must already be in view space — use clip_plane_to_view_space() to convert world-space planes first. A vertex is considered "inside" (kept) when: dot(view_pos, plane.normal) + plane.offset >= 0.

Parameters

	v0,v1,v2	Triangle vertex positions in view space.
	n0,n1,n2	Per-vertex normals (view space).
	c0,c1,c2	Per-vertex colors.
	uv0,uv1,uv2	Per-vertex texture coordinates.
	plane	The clipping plane.
[out]	output_vertices	Clipped vertices (positions are in view space — caller must transform to clip space).
[out]	output_triangles	Resulting triangle indices.

Returns

Number of output triangles (0, 1, or 2).

See also

clip_plane_to_view_space(), clip_triangle_near_plane(), ClipPlane, RenderOptions::clip_planes

Definition at line 162 of file clipping.cpp.

compute_barycentric()

void scimesh::compute_barycentric ( float  px, float  py, float  x0, float  y0, float  x1, float  y1, float  x2, float  y2, float &  u, float &  v, float &  w  )

inline

Compute barycentric coordinates (u, v, w) of a point in a triangle.

Barycentric coordinates tell you how much each vertex contributes to a point inside the triangle. They are used for interpolating colors, normals, and depth across the triangle surface.

• u + v + w = 1.0
• All three are in [0, 1] if and only if the point is inside the triangle.

Parameters

	px,py	The query point (2D screen coords).
	x0,y0,x1,y1,x2,y2	Triangle vertices (2D screen coords).
[out]	u,v,w	Output barycentric weights.

Example: checking if a point is inside a triangle

float u, v, w;
compute_barycentric(px, py, x0, y0, x1, y1, x2, y2, u, v, w);
if (u >= 0 && v >= 0 && w >= 0) {
    // point is inside the triangle
}

Definition at line 158 of file math_utils.h.

compute_face_normal()

Vec3 scimesh::compute_face_normal ( const Vec3 &  v0, const Vec3 &  v1, const Vec3 &  v2  )

inline

Compute the unit-length normal vector of a triangle face.

Uses the cross product of two edges. The normal points according to the right-hand rule: if vertices are ordered counter-clockwise when viewed from the front, the normal points toward the viewer.

Parameters

v0,v1,v2

The three triangle vertex positions.

Returns

A unit-length Vec3 perpendicular to the triangle. Returns (0, 0, 1) for degenerate (zero-area) triangles.

Example

Vec3 n = compute_face_normal({0,0,0}, {1,0,0}, {0,1,0});
// n = (0, 0, 1) — pointing out of the XY plane

See also

compute_vertex_normals()

Definition at line 37 of file math_utils.h.

compute_vertex_normals()

void scimesh::compute_vertex_normals	(	const Mesh &	mesh,
		std::vector< Vec3 > &	normals
	)

Compute per-vertex normals by averaging adjacent face normals.

For each vertex, this function finds all triangles that share that vertex, computes each triangle's face normal using compute_face_normal(), and averages them together (weighted equally). The resulting normals are suitable for smooth (Gouraud) shading.

Parameters

[in]	mesh	The input mesh (only vertices and triangles are read).
[out]	normals	Output array — will be resized to mesh.vertices.size() and filled with unit-length normal vectors.

When do I need this?

Most file formats (OBJ, PLY, STL) may or may not include normals. If you load a mesh and mesh.has_normals() returns false, call this function to compute them before rendering with ShadingMode::SMOOTH.

Example

Mesh m = scimesh::obj_io::read_obj("model.obj");
if (!m.has_normals()) {
    compute_vertex_normals(m, m.normals);
}
// now render with smooth shading

See also

compute_face_normal(), Mesh::normals, Mesh::has_normals(), ShadingMode

Definition at line 5 of file normals.cpp.

convert_fs_mesh() [1/4]

Mesh scimesh::convert_fs_mesh ( const fs::Mesh &  fs_mesh )

inline

Convert a FreeSurfer mesh to a scimesh Mesh (no colors).

Copies vertex positions and face indices. No colors are set — you should set Mesh::default_color or populate Mesh::colors before rendering.

Parameters

fs_mesh

The FreeSurfer mesh to convert.

Returns

A scimesh Mesh with vertices and triangles populated.

Example

fs::Mesh fs_brain = fs::read_fs_mesh("lh.white");
Mesh brain = scimesh::convert_fs_mesh(fs_brain);
brain.default_color = Color(0.7f, 0.7f, 0.7f);

See also

convert_fs_mesh(const fs::Mesh&, const Color&), convert_fs_mesh(const fs::Mesh&, const std::vector<uint8_t>&)

Definition at line 37 of file fs_mesh_converter.h.

convert_fs_mesh() [2/4]

Mesh scimesh::convert_fs_mesh ( const fs::Mesh &  fs_mesh, const Color &  solid_color  )

inline

Convert a FreeSurfer mesh to a scimesh Mesh with a solid color.

All vertices are assigned the same solid_color. This is a convenience wrapper — it calls the basic converter, then fills mesh.colors.

Parameters

fs_mesh	The FreeSurfer mesh to convert.
solid_color	The uniform color to assign to all vertices.

Returns

A scimesh Mesh with vertices, triangles, and per-vertex colors.

Example

fs::Mesh fs_brain = fs::read_fs_mesh("lh.white");
Mesh brain = scimesh::convert_fs_mesh(fs_brain, Color(0.5f, 0.5f, 0.5f));

See also

convert_fs_mesh(const fs::Mesh&)

Definition at line 74 of file fs_mesh_converter.h.

convert_fs_mesh() [3/4]

Mesh scimesh::convert_fs_mesh ( const fs::Mesh &  fs_mesh, const std::vector< float > &  morph_data, const std::vector< uint8_t > &  rgb_colors, float  nan_alpha = 1.0f  )

inline

Convert a FreeSurfer mesh with per-vertex morphological data and RGB coloring.

This is the most feature-rich converter. Each vertex gets:

• An RGB color from rgb_colors (3 bytes per vertex).
• If morph_data[i] is NaN, the vertex is colored white with alpha nan_alpha (often used to mark the medial wall or "unknown" regions in brain surface data).

Parameters

fs_mesh	The FreeSurfer mesh to convert.
morph_data	Per-vertex scalar values (NaN = mark as white).
rgb_colors	Flat array of RGB bytes (size = 3 × vertex count).
nan_alpha	Alpha for the NaN vertices. The default (1.0) renders them as opaque white. Pass 0.0 to punch holes (the renderer then shows the geometry behind the medial wall) or an intermediate value such as 0.5 to draw it translucently. Any value < 1 switches the mesh to the alpha-blending pass.

Returns

A scimesh Mesh with per-vertex colors.

Example

fs::Mesh fs_brain = fs::read_fs_mesh("lh.white");
std::vector<float> curv = fs::read_curv("lh.thickness");
std::vector<uint8_t> rgb = fs_mesh.get_vertex_rgb();
// Medial wall (NaN) rendered half transparent:
Mesh brain = scimesh::convert_fs_mesh(fs_brain, curv, rgb, 0.5f);

See also

convert_fs_mesh(const fs::Mesh&, const std::vector<uint8_t>&)

mesh_from_fs()

Definition at line 148 of file fs_mesh_converter.h.

convert_fs_mesh() [4/4]

Mesh scimesh::convert_fs_mesh ( const fs::Mesh &  fs_mesh, const std::vector< uint8_t > &  rgb_colors  )

inline

Convert a FreeSurfer mesh with per-vertex RGB coloring.

Each vertex gets a color from the rgb_colors array (3 bytes per vertex: red, green, blue, each 0–255).

Parameters

fs_mesh	The FreeSurfer mesh to convert.
rgb_colors	Flat array of RGB bytes (size = 3 × vertex count).

Returns

A scimesh Mesh with per-vertex colors.

Example

std::vector<uint8_t> rgb = fs_mesh.get_vertex_rgb();
Mesh brain = scimesh::convert_fs_mesh(fs_mesh, rgb);

See also

convert_fs_mesh(const fs::Mesh&, const Color&)

Definition at line 101 of file fs_mesh_converter.h.

default_font_path()

std::string scimesh::default_font_path

(

)

Path of the bundled default font, or as overridden by the SCIMESH_FONT environment variable.

Resolution order:

1. the SCIMESH_FONT environment variable, when set and readable,
2. the default font path compiled into the library: for builds from the scimesh source tree that is the bundled <source>/inst/extdata/Inter-Regular.ttf, and installed copies also ship it as <prefix>/share/scimesh/fonts/Inter-Regular.ttf (pass that path explicitly, or via SCIMESH_FONT, when the source tree is gone),
3. a few paths relative to the current working directory, which is what makes the bundled font work when running from the source tree or from an example build directory.

Returns

A readable path to a .ttf file, or an empty string when none of the candidates exist.

Definition at line 371 of file font.cpp.

draw_text()

void scimesh::draw_text	(	Image &	image,
		const std::string &	text,
		const Font &	font,
		float	x,
		float	baseline_y,
		const TextDrawStyle &	style = TextDrawStyle()
	)

Draw text into an image at a given position and baseline.

This is the low-level drawing primitive: it places the text's left edge at x and its first baseline at baseline_y, in image pixels. y grows downwards, matching the image row order and the screen coordinates produced by ndc_to_screen(). Multi-line strings (separated by \n) are drawn with the line spacing from style, all lines left-aligned at x.

Glyphs are alpha-blended over whatever is already in the image, so this can be called on an image produced by any of the renderers. Measurements for layouts come from Font::measure() and Font::metrics().

Example

Font font = cached_font("", 20.0f);
draw_text(img, "anterior", font, 20.0f, 40.0f, TextDrawStyle());
 
// A y-axis style label, reading bottom to top:
TextDrawStyle rotated;
rotated.rotation = 90.0f;
draw_text(img, "intensity", font, 20.0f, 40.0f, rotated);

Parameters

[in,out]	image	The image to draw into.
	text	UTF-8 text; \n starts a new line.
	font	A loaded font (see cached_font()).
	x	X position of the left edge of the text, in pixels.
	baseline_y	Y position of the first baseline, in pixels.
	style	Colors, halo, line spacing and rotation.

See also

TextLayer, Font, TextDrawStyle

Definition at line 406 of file text.cpp.

flip_uvs()

void scimesh::flip_uvs

(

Mesh &

mesh

)

Flip the texture coordinates of a mesh vertically (v → 1 − v).

scimesh stores UVs in image space, with v = 0 at the top edge of the texture image (see Mesh::uvs). OBJ and PLY files, OpenGL, rgl and tools such as Blender and MeshLab use the opposite convention, with v = 0 at the bottom. Call this once on a mesh whose UVs come from such a source, instead of rewriting the coordinates by hand (this is exactly what the examples/cpp/spot_cow/ example needs for its OBJ texture coordinates).

Mesh geometry, colors and normals are untouched. Meshes without UVs are left as they are, so this is safe to call unconditionally.

Parameters

mesh	The mesh whose UVs to flip (modified in place).

Example

Mesh model = obj_io::read_obj("model.obj");
model.uvs = uvs_from_obj;   // bottom-left origin, e.g. from libfs
flip_uvs(model);            // now v = 0 is the top of the texture

See also

Mesh::uvs, transform_mesh()

Definition at line 134 of file transforms.cpp.

fmt_count()

std::string scimesh::fmt_count ( size_t  n )

inline

Definition at line 56 of file to_string.h.

fmt_size_bytes()

std::string scimesh::fmt_size_bytes ( size_t  bytes )

inline

Definition at line 70 of file to_string.h.

generate_arrow()

Mesh scimesh::generate_arrow	(	const Vec3 &	from,
		const Vec3 &	to,
		float	shaft_radius,
		float	head_radius,
		float	head_length,
		int	segments,
		const Color &	color
	)

Generate a 3D arrow from from to to.

An arrow consists of a cylindrical shaft and a conical head. The arrow points from from toward to. Both parts share the same color.

Parameters

from	Starting point (tail of the arrow).
to	Ending point (tip of the arrowhead).
shaft_radius	Radius of the cylindrical shaft.
head_radius	Radius of the cone base (arrowhead width).
head_length	Length of the arrowhead along the arrow direction.
segments	Number of sides around the circumference.
color	Uniform color.

Returns

A new Mesh with normals.

Example

// Red arrow from origin to (3, 0, 0)
Mesh arrow = generate_arrow({0,0,0}, {3,0,0}, 0.1f, 0.3f, 0.6f, 16,
                              Color(1,0,0));

See also

generate_cylinder(), generate_cone()

Definition at line 341 of file primitives.cpp.

generate_cone()

Mesh scimesh::generate_cone	(	const Vec3 &	base,
		const Vec3 &	tip,
		float	radius,
		int	segments,
		const Color &	color
	)

Generate a cone from a base circle to a tip point.

The cone has a circular base centered at base, tapering to a point at tip. The base cap is included.

Parameters

base	Center of the circular base.
tip	The apex (pointy end) of the cone.
radius	Radius of the base.
segments	Number of sides (≥ 3).
color	Uniform color.

Returns

A new Mesh with normals.

Example

Mesh cone = generate_cone({0,0,0}, {0,3,0}, 1.0f, 16,
                           Color(1.0f, 0.5f, 0.0f));

See also

generate_cylinder(), generate_pyramid()

Definition at line 265 of file primitives.cpp.

generate_cuboid()

Mesh scimesh::generate_cuboid	(	const Vec3 &	center,
		const Vec3 &	half_extents,
		const Color &	color
	)

Generate an axis-aligned cuboid (rectangular box).

The box is centered at center and extends half_extents in each direction (i.e., the full dimensions are 2 * half_extents).

Parameters

center	Center of the box.
half_extents	Half-width, half-height, half-depth (all positive).
color	Uniform color.

Returns

A new Mesh with normals.

Example

// A 2×1×3 box centered at the origin
Mesh box = generate_cuboid({0,0,0}, {1, 0.5, 1.5}, Color(0.5, 0.5, 0.5));

See also

generate_sphere(), generate_pyramid()

Definition at line 690 of file primitives.cpp.

generate_cylinder()

Mesh scimesh::generate_cylinder	(	const Vec3 &	start,
		const Vec3 &	end,
		float	radius,
		int	segments,
		const Color &	color,
		bool	caps = true
	)

Generate a cylinder between two endpoints.

The cylinder runs from start to end with a circular cross-section of the given radius. By default end caps are included; pass caps = false for an open tube, which uses roughly half the geometry (4 * segments + 2 vertices with caps vs. 2 * segments without, for the same segment count). Open tubes are the better choice whenever the ends are not visible, e.g. edges of a network graph whose nodes are drawn as spheres, or wireframe-like line bundles.

Parameters

start	Starting point (center of bottom cap).
end	Ending point (center of top cap).
radius	Radius of the cylinder.
segments	Number of sides around the circumference (≥ 3).
color	Uniform color.
caps	Whether to close both ends with triangle fans (default: true).

Returns

A new Mesh with normals.

Example

Mesh pillar = generate_cylinder({0,0,0}, {0,5,0}, 0.5f, 16,
                                 Color(0.7f, 0.7f, 0.7f));
// Open tube, half the geometry (e.g. for graph edges):
Mesh edge = generate_cylinder({0,0,0}, {0,5,0}, 0.05f, 8,
                               Color(0.7f, 0.7f, 0.7f), false);

See also

generate_cone(), generate_arrow(), generate_multi_cylinders()

Definition at line 159 of file primitives.cpp.

generate_multi_cylinders()

Mesh scimesh::generate_multi_cylinders	(	const std::vector< Vec3 > &	starts,
		const std::vector< Vec3 > &	ends,
		const std::vector< float > &	radii,
		const std::vector< Color > &	colors,
		int	segments = 12,
		bool	caps = true
	)

Generate multiple cylinders in a single mesh (efficient batching).

Much faster than calling generate_cylinder() many times — all cylinders share a single mesh.

Parameters

starts	Array of start points.
ends	Array of end points (same length as starts).
radii	Array of radii (recycled from the first entry if shorter; an empty array means radius 1.0).
colors	Array of colors (recycled from the first entry if shorter; an empty array means white).
segments	Subdivisions per cylinder (default: 12).
caps	Whether to close both ends of each cylinder (default: true, see generate_cylinder()). Pass false to save about half of the vertices/triangles when the ends are hidden.

Returns

A single Mesh containing all cylinders.

Example

std::vector<Vec3> starts = {{0,0,0}, {1,0,0}};
std::vector<Vec3> ends   = {{0,3,0}, {1,3,0}};
std::vector<float> rads  = {0.1f, 0.1f};
std::vector<Color> cols  = {Color(1,1,1), Color(1,1,1)};
Mesh pillars = generate_multi_cylinders(starts, ends, rads, cols, 12);

See also

generate_cylinder(), generate_multi_spheres()

Definition at line 402 of file primitives.cpp.

generate_multi_spheres()

Mesh scimesh::generate_multi_spheres	(	const std::vector< Vec3 > &	centers,
		const std::vector< float > &	radii,
		const std::vector< Color > &	colors,
		int	segments = 16
	)

Generate multiple spheres in a single mesh (efficient batching).

Much faster than calling generate_sphere() many times and merging — all spheres share a single mesh with one vertex/triangle array.

Parameters

centers	Array of center points.
radii	Array of radii (recycled from the first entry if shorter; an empty array means radius 1.0).
colors	Array of colors (recycled from the first entry if shorter; an empty array means white).
segments	Subdivisions per sphere (default: 16).

Returns

A single Mesh containing all spheres.

Example

std::vector<Vec3> pts = {{0,0,0}, {2,0,0}, {0,2,0}};
std::vector<float> rads = {0.5, 0.3, 0.4};
std::vector<Color> cls = {Color(1,0,0), Color(0,1,0), Color(0,0,1)};
Mesh spheres = generate_multi_spheres(pts, rads, cls, 16);

See also

generate_sphere(), generate_multi_cylinders()

Definition at line 374 of file primitives.cpp.

generate_multi_tubes()

Mesh scimesh::generate_multi_tubes	(	const std::vector< std::vector< Vec3 > > &	paths,
		const std::vector< float > &	radii,
		const std::vector< Color > &	colors,
		int	segments = 12,
		bool	caps = false
	)

Generate multiple tubes in a single mesh (efficient batching).

Much faster than calling generate_tube() many times and merging — all tubes share a single mesh with one vertex/triangle array. The paths may differ in length; short or degenerate paths simply contribute no geometry.

Parameters

paths	Array of paths, each a vector of points (≥ 2 distinct points per path for it to produce geometry).
radii	Array of radii (recycled from the first entry if shorter; an empty array means radius 1.0).
colors	Array of colors (recycled from the first entry if shorter; an empty array means white).
segments	Subdivisions around the circumference (default: 12).
caps	Whether to close both ends of every tube (default: false, since batched tubes are typically connected at the ends).

Returns

A single Mesh containing all tubes.

Example

std::vector<std::vector<Vec3>> paths = {
    {{0,0,0}, {1,1,0}, {2,0,0}},
    {{0,0,1}, {1,1,1}, {2,0,1}}}
;
std::vector<float> rads = {0.1f, 0.1f};
std::vector<Color> cols = {Color(1,0,0), Color(0,0,1)};
Mesh tubes = generate_multi_tubes(paths, rads, cols, 12, false);

See also

generate_tube(), generate_multi_cylinders()

Definition at line 656 of file primitives.cpp.

generate_plane()

Mesh scimesh::generate_plane	(	const Vec3 &	center,
		const Vec3 &	normal,
		float	half_size_x,
		float	half_size_y,
		const Color &	color
	)

Generate a flat rectangular plane.

The plane is a single quad (two triangles) centered at center, oriented perpendicular to the given normal.

Parameters

center	Center point of the plane.
normal	Surface normal (direction the plane faces).
half_size_x	Half the width in the local X direction.
half_size_y	Half the height in the local Y direction.
color	Uniform color.

Returns

A new Mesh with normals.

Example

Mesh floor = generate_plane({0,-1,0}, {0,1,0}, 10.0f, 10.0f,
                              Color(0.3f, 0.3f, 0.3f));

See also

generate_cuboid()

Definition at line 919 of file primitives.cpp.

generate_pyramid()

Mesh scimesh::generate_pyramid	(	const Vec3 &	base_center,
		const Vec3 &	apex,
		float	half_width,
		const Color &	color
	)

Generate a square-based pyramid.

The base is a square in the XZ plane centered at base_center. The apex is above the base.

Parameters

base_center	Center of the square base.
apex	The top point (tip) of the pyramid.
half_width	Half the side length of the square base.
color	Uniform color.

Returns

A new Mesh with normals.

Example

Mesh pyramid = generate_pyramid({0,0,0}, {0,2,0}, 1.0f,
                                  Color(0.8f, 0.6f, 0.2f));

See also

generate_cone(), generate_tetrahedron()

Definition at line 753 of file primitives.cpp.

generate_sphere()

Mesh scimesh::generate_sphere	(	const Vec3 &	center,
		float	radius,
		int	segments,
		const Color &	color
	)

Generate a UV-sphere (latitude/longitude tessellation).

The sphere is centered at center with the given radius. The segments parameter controls how smooth it looks — more segments = rounder but more triangles.

Parameters

center	Center point of the sphere.
radius	Radius (half the diameter).
segments	Number of subdivisions (≥ 3). Typical: 16 (low-poly) to 64 (smooth). The sphere has segments * segments * 2 triangles.
color	Uniform color for all vertices.

Returns

A new Mesh with vertices, triangles, and per-vertex normals.

Example

Mesh ball = generate_sphere({0,0,0}, 1.0f, 32, Color(0.2f, 0.5f, 0.8f));

See also

generate_torus(), generate_cylinder()

Definition at line 84 of file primitives.cpp.

generate_tetrahedron()

Mesh scimesh::generate_tetrahedron	(	const Vec3 &	p0,
		const Vec3 &	p1,
		const Vec3 &	p2,
		const Vec3 &	p3,
		const Color &	color
	)

Generate a tetrahedron (triangular pyramid) from four points.

A tetrahedron is the simplest 3D shape — a pyramid with a triangular base and three triangular sides.

Parameters

p0,p1,p2,p3	The four corner points.
color	Uniform color.

Returns

A new Mesh.

Example

Mesh tet = generate_tetrahedron(
    {0,0,0}, {1,0,0}, {0,1,0}, {0,0,1},
    Color(0.3f, 0.7f, 0.3f));

See also

generate_pyramid()

Definition at line 816 of file primitives.cpp.

generate_torus()

Mesh scimesh::generate_torus	(	const Vec3 &	center,
		float	major_radius,
		float	minor_radius,
		int	major_segments,
		int	minor_segments,
		const Color &	color
	)

Generate a torus (donut shape).

A torus is the surface of a ring. major_radius is the distance from the center of the hole to the center of the tube. minor_radius is the radius of the tube itself.

Parameters

center	Center of the torus.
major_radius	Distance from hole center to tube center.
minor_radius	Radius of the tube cross-section.
major_segments	Subdivisions around the ring (≥ 4).
minor_segments	Subdivisions around the tube (≥ 4).
color	Uniform color.

Returns

A new Mesh with normals.

Example

Mesh donut = generate_torus({0,0,0}, 2.0f, 0.5f, 32, 16,
                              Color(0.9f, 0.6f, 0.3f));

See also

generate_sphere(), generate_cylinder()

Definition at line 862 of file primitives.cpp.

generate_tube()

Mesh scimesh::generate_tube	(	const std::vector< Vec3 > &	path,
		float	radius,
		int	segments,
		const Color &	color,
		bool	cap_start = true,
		bool	cap_end = true
	)

Generate a tube (generalized cylinder) along a polyline path.

Sweeps a circular cross-section of the given radius along the points of path, which allows for curved shapes (arches, Bezier samples, streamlines, graph edges drawn as arcs). A path of exactly two points produces the same shape as generate_cylinder().

The cross-section frames are computed by parallel transport (rotation-minimizing frames): the frame of each ring is derived from the previous ring by the minimal rotation between the two tangents. This keeps the tube from twisting around its own axis. Interior tangent directions are mitered (the direction from the previous to the next path point), so joints between segments stay watertight; note that very sharp turns pinch the tube slightly on the inside of the bend.

Consecutive duplicate path points are removed. If fewer than two distinct points remain, an empty mesh is returned.

Parameters

path	Path points to sweep along (at least 2 distinct points).
radius	Radius of the tube.
segments	Number of sides around the circumference (≥ 3).
color	Uniform color.
cap_start	Whether to close the beginning with a triangle fan (default: true).
cap_end	Whether to close the end with a triangle fan (default: true).

Returns

A new Mesh with normals (radial, pointing away from the centerline).

Example

// A curved tube through three points, open at both ends:
std::vector<Vec3> path = {{0,0,0}, {1,1,0}, {2,0,0}};
Mesh arc = generate_tube(path, 0.1f, 12, Color(0.8f, 0.2f, 0.2f),
                         false, false);

See also

generate_cylinder(), generate_multi_tubes()

Definition at line 532 of file primitives.cpp.

grid_arrange()

Image scimesh::grid_arrange	(	const std::vector< Image > &	images,
		int	ncol = 0,
		int	nrow = 0,
		FitMode	fit_mode = FitMode::PAD,
		const Color &	background = Color(1.0f, 1.0f, 1.0f, 1.0f)
	)

Arrange a list of images into a grid layout.

Images are placed left-to-right, top-to-bottom in an ncol × nrow grid. If the number of images is less than ncol * nrow, remaining cells are filled with background. Before placement, all images are normalized to the same cell size using fit_mode.

Parameters

images	The list of images to arrange.
ncol	Number of columns (0 = auto-compute from nrow).
nrow	Number of rows (0 = auto-compute from ncol). If both are 0, a square-ish layout is chosen.
fit_mode	How to handle size mismatches (PAD or SCALE).
background	Fill color for padding and empty cells.

Returns

A new Image containing the arranged grid.

Example

Image grid = grid_arrange({view1, view2, view3, view4}, 2, 2,
                           FitMode::PAD, Color(1,1,1));

See also

FitMode, Image::pad_to_size(), Image::scale()

Definition at line 560 of file image.cpp.

hermite_path()

std::vector< Vec3 > scimesh::hermite_path ( const std::vector< Vec3 > &  points, const std::vector< Vec3 > &  tangents, int  samples_per_segment = 8, bool  closed = false  )

inline

Sample a cubic Hermite curve with caller-supplied tangents.

The general form of every curve in this header: the curve passes through every input point, and the shape between two points is a cubic that is fully determined by the two points and their two tangent vectors. Control over the tangents is what lets you make a path leave a point in a direction that is meaningful for your data (a heading, a surface normal, a symmetry axis) rather than the one a global rule picks for you.

Tangents are given in the units of the local segment parameter, i.e. laying tangents[i] end to end at points[i] points in the direction the curve leaves the point. Each segment is parameterized over [0, 1] independently, so a segment with very different length than its neighbours will show a visible change of speed — which does not matter for a swept tube (generate_tube() only uses the positions), but does matter if you sample the curve for constant-speed motion.

Parameters

points	Points the curve has to pass through (at least 2).
tangents	One tangent vector per point (same size as points).
samples_per_segment	Samples per segment (clamped to at least 1).
closed	Whether the curve loops back to its first point.

Returns

The sampled path, or an empty vector if the input is unusable (fewer than two points, mismatched tangent count, or a closed curve with fewer than three points).

Example

std::vector<Vec3> pts = {{0,0,0}, {1,0,0}, {2,0,0}};
std::vector<Vec3> tan = {{0,0,1}, {0,0,1}, {0,0,1}};  // leave each point "upward"
std::vector<Vec3> path = hermite_path(pts, tan, 8);

See also

catmull_rom_path()

Definition at line 423 of file spline.h.

max_ortho_extent()

float scimesh::max_ortho_extent ( const Vec3 &  bmin, const Vec3 &  bmax, const Vec3 &  center, const Vec3 &  dir  )

inline

Compute the maximum perpendicular extent of an AABB from a view ray (for orthographic projection framing).

Unlike perp_extent_radius(), this does not depend on field of view — it is used to set the orthographic frustum size.

Parameters

bmin	Minimum corner of the AABB.
bmax	Maximum corner of the AABB.
center	The center point the camera looks at.
dir	The view direction.

Returns

The maximum perpendicular distance from the ray through center.

See also

perp_extent_radius(), camera_look_at()

Definition at line 254 of file camera.h.

measure_text()

TextExtent scimesh::measure_text	(	const std::string &	text,
		float	size,
		const std::string &	font_file = "",
		float	line_spacing = 1.2f
	)

Measure a (possibly multi-line) string in a given font and size.

Uses exactly the same layout as the renderer (same line splitting, same line spacing), so the result matches the drawn label.

Parameters

text	UTF-8 text; \n starts a new line.
size	Text height in output pixels.
font_file	Path to a .ttf file, or an empty string for the bundled default font.
line_spacing	Distance between lines, as a multiple of the font's glyph box height (default: 1.2).

Returns

The text extent, see TextExtent.

Exceptions

std::invalid_argument	If size is not positive.
std::runtime_error	If the font cannot be loaded.

Example

TextExtent ext = measure_text("anterior", 18.0f);
// place the text box in the top right corner of an 800x600 image
float x = 800.0f - ext.width - 10.0f;

See also

TextExtent, Font::measure()

Definition at line 422 of file text.cpp.

merge_mesh()

void scimesh::merge_mesh	(	Mesh &	dst,
		const Mesh &	src
	)

Merge one mesh into another (append geometry).

All vertices, triangles, colors, normals, and UVs from src are appended to dst. Triangle indices in src are offset to account for existing vertices in dst.

Parameters

[in,out]	dst	The destination mesh (modified in-place).
	src	The source mesh (not modified).

Example

Mesh combined = generate_sphere({-1,0,0}, 0.5f, 16, Color(1,0,0));
merge_mesh(combined, generate_sphere({1,0,0}, 0.5f, 16, Color(0,1,0)));
// combined now has two spheres

See also

generate_multi_spheres(), generate_multi_cylinders()

Definition at line 361 of file primitives.cpp.

mesh_from_fs()

Mesh scimesh::mesh_from_fs	(	const std::vector< float > &	fs_vertices,
		const std::vector< uint32_t > &	fs_faces,
		const std::vector< float > &	per_vertex_values = {},
		const std::vector< uint8_t > &	rgb_bytes = {},
		bool	detect_transparency = false
	)

Convert a FreeSurfer-format mesh (flat vertex/face arrays) to a scimesh Mesh.

FreeSurfer is a neuroimaging software suite. Its mesh format stores vertices as a flat float array (3 per vertex) and faces as a flat uint32_t array (3 per face). This function converts those raw arrays into a scimesh Mesh with optional per-vertex coloring.

Parameters

fs_vertices	Flat array of vertex coordinates (x0,y0,z0, x1,y1,z1, ...).
fs_faces	Flat array of face indices (v0,v1,v2, v0,v1,v2, ...).
per_vertex_values	Optional scalar per-vertex values for coloring.
rgb_bytes	Optional RGB color bytes (3 per vertex: r,g,b, ...).
detect_transparency	If true, check for NaN values indicating transparent regions (common in brain surface data).

Returns

A scimesh Mesh.

Example

std::vector<float> verts = {0,0,0, 1,0,0, 0,1,0, 1,1,0};
std::vector<uint32_t> faces = {0,1,2, 1,3,2};
Mesh m = mesh_from_fs(verts, faces);

See also

Mesh, fs_mesh_converter.h

Definition at line 84 of file transforms.cpp.

ndc_to_screen()

void scimesh::ndc_to_screen ( const Vec3 &  ndc, int  width, int  height, float &  screen_x, float &  screen_y, float &  depth  )

inline

Convert from normalized device coordinates (NDC) to screen (pixel) coordinates.

NDC space is a cube from (-1,-1,-1) to (1,1,1). This maps it to pixel coordinates where (0,0) is the top-left corner.

Parameters

	ndc	Input NDC coordinates.
	width	Screen width in pixels.
	height	Screen height in pixels.
[out]	screen_x	Output X pixel coordinate.
[out]	screen_y	Output Y pixel coordinate (0 = top).
[out]	depth	Output depth value (passed through from NDC z).

See also

perspective_divide()

Definition at line 125 of file math_utils.h.

operator<<() [1/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Camera &  cam  )

inline

Definition at line 126 of file to_string.h.

operator<<() [2/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const ClipPlane &  cp  )

inline

Definition at line 120 of file to_string.h.

operator<<() [3/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Color &  c  )

inline

Definition at line 86 of file to_string.h.

operator<<() [4/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Image &  img  )

inline

Definition at line 165 of file to_string.h.

operator<<() [5/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Light &  l  )

inline

Definition at line 113 of file to_string.h.

operator<<() [6/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Mesh &  m  )

inline

Definition at line 136 of file to_string.h.

operator<<() [7/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const RenderOptions &  opts  )

inline

Definition at line 172 of file to_string.h.

operator<<() [8/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Scene &  s  )

inline

Definition at line 154 of file to_string.h.

operator<<() [9/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Triangle &  t  )

inline

Definition at line 96 of file to_string.h.

operator<<() [10/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, const Vec3 &  v  )

inline

Definition at line 91 of file to_string.h.

operator<<() [11/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, ProjectionType  p  )

inline

Definition at line 106 of file to_string.h.

operator<<() [12/12]

std::ostream & scimesh::operator<< ( std::ostream &  os, ShadingMode  s  )

inline

Definition at line 101 of file to_string.h.

path_curvature()

std::vector< float > scimesh::path_curvature ( const std::vector< Vec3 > &  path, bool  closed = false  )

inline

Discrete curvature at every point of a path.

Estimates the curvature with the standard formula ‘kappa = |x’ x x''| / |x'|^3, which is invariant under reparameterization (so it does not care how the points are spaced), using central differences for the two derivatives. Withv = P[i+1] - P[i-1]and a = P[i+1] - 2*P[i] + P[i-1]this reduces to4 * |v x a| / |v|^3: the derivatives arex' = v / (2h)andx'' = a / h^2, so theh-dependence cancels up to the factor that comes from the central first difference. (Dropping that factor makes every curvature four times too small, which is invisible on a curve whose curvature you are guessing at and very visible on a circle, where the estimate has to come out as1 / radius`.)

The endpoints of an open path report the value of their only neighbour, since curvature is not defined from one side.

This is a diagnostic tool rather than a rendering input: sweeping a tube of radius r along a curve whose curvature reaches kappa folds the tube inside out, so a path is safe up to a radius of 1 / max(kappa) (see generate_tube()).

Parameters

path	Points of the path.
closed	Whether the path loops back to its first point.

Returns

One curvature value per input point (empty for fewer than three points, where curvature is undefined).

Example

// A circle of radius 2: curvature is 0.5 everywhere.
std::vector<float> k = path_curvature(circle_points, true);

See also

generate_tube(), path_tangents()

Definition at line 253 of file spline.h.

path_length()

float scimesh::path_length ( const std::vector< Vec3 > &  path, bool  closed = false  )

inline

Total length of a polyline path.

Sums the distances between consecutive points, plus the closing distance from the last point back to the first for a closed path.

Parameters

path	Points of the path.
closed	Whether the path loops back to its first point.

Returns

The arc length of the path (0 for fewer than two points).

Example

float len = path_length({{0,0,0}, {1,0,0}, {1,1,0}});  // 2.0f

See also

resample_by_arclength()

Definition at line 138 of file spline.h.

path_tangents()

std::vector< Vec3 > scimesh::path_tangents ( const std::vector< Vec3 > &  path, bool  closed = false  )

inline

Unit tangent direction at every point of a path.

Interior points use the direction from the previous to the next point (a mitered joint), the endpoints use the direction of their only adjacent segment, and closed paths wrap around. Points whose neighbourhood is degenerate (coincident points) inherit the previous direction, and a path that has no direction at all reports (0, 0, 1).

Parameters

path	Points of the path.
closed	Whether the path loops back to its first point.

Returns

One unit vector per input point (empty for fewer than two points).

See also

path_curvature()

Definition at line 185 of file spline.h.

perp_extent_radius()

float scimesh::perp_extent_radius ( const Vec3 &  bmin, const Vec3 &  bmax, const Vec3 &  center, const Vec3 &  dir, float  fov_radians, float *  out_dist = nullptr  )

inline

Compute the "perpendicular extent radius" of an axis-aligned bounding box relative to a view direction.

This is an internal helper used by camera_look_at() to compute how far the camera needs to be to keep the entire bounding box in view. It is tighter than a simple sphere-based method because it accounts for the actual box shape.

Parameters

	bmin	Minimum corner of the AABB.
	bmax	Maximum corner of the AABB.
	center	The center point the camera looks at.
	dir	The view direction (forward vector).
	fov_radians	Vertical FOV in radians.
[out]	out_dist	Optional: receives the computed camera distance.

Returns

The equivalent sphere radius.

See also

camera_look_at()

Definition at line 207 of file camera.h.

perspective_divide()

Vec3 scimesh::perspective_divide ( const Vec4 &  clip )

inline

Perform perspective division: divide xyz by w.

Converts from homogeneous clip space to normalized device coordinates (NDC). If w is near zero (the point is at the camera plane), the result is clamped to avoid division by zero.

Parameters

clip	A point in homogeneous clip space.

Returns

The point after division by w.

See also

transform_point_homogeneous(), ndc_to_screen()

Definition at line 105 of file math_utils.h.

remove_duplicate_points()

std::vector< Vec3 > scimesh::remove_duplicate_points ( const std::vector< Vec3 > &  path, float  epsilon = 1e-6f  )

inline

Remove points that repeat their predecessor.

Duplicate (or nearly duplicate) points carry no direction, so they make the frame construction of a swept tube degenerate and waste samples of a spline. Comparison is against the previously kept point, so a run of duplicates collapses to its first point.

Parameters

path	Points of the path.
epsilon	Minimum distance for two points to count as distinct.

Returns

The cleaned path (the first point is always kept).

See also

generate_tube()

Definition at line 160 of file spline.h.

resample_by_arclength()

std::vector< Vec3 > scimesh::resample_by_arclength ( const std::vector< Vec3 > &  path, float  step, bool  closed = false  )

inline

Resample a path at a fixed arc-length step.

Walks along the polyline and emits a point every step units of arc length, starting at the first point. The result has (nearly) uniform point spacing regardless of how the input was parameterized, which is what makes a swept tube look even: generate_tube() places exactly one cross-section per path point, so uneven spacing means a tube that is finely subdivided in one place and faceted in another.

The sample count is driven by the length, not by the input: a long straight run produces many points and a tight bend few, exactly as a constant-speed traversal would. An open path always keeps its final point (the last step is shortened by whatever is left over). A closed path ends with a copy of its first point, like the closed curves of the sampling functions, and its step is adjusted to the exact loop length while doing so: the remainder of the division would otherwise collect into a single arbitrary gap at the seam, and a short enough gap there means two overlapping cross-sections in a swept tube. The adjustment is at most half a step divided by the number of samples (under 1 % from 50 samples on).

Note

This is a reparameterization, not a resampling filter: the emitted points lie on the input segments, so a corner between two input segments is cut off if it does not happen to fall on a sample boundary. Resample the output of a spline (where the "corners" are sampling artifacts), not a hand-written polyline whose vertices are meaningful. The spacing that is uniform is the arc length along the path; the straight-line distances between consecutive samples are slightly shorter wherever the path curves, by the usual chord-versus-arc difference (0.7 % at a step of 0.25 on a curve of radius 1).

Parameters

path	Points of the path.
step	Arc length between samples (> 0; other values return the path unchanged).
closed	Whether the path loops back to its first point.

Returns

The resampled path.

Example

std::vector<Vec3> smooth = catmull_rom_path(waypoints, 8);
std::vector<Vec3> even = resample_by_arclength(smooth, 0.25f);

See also

path_length(), catmull_rom_path()

Definition at line 333 of file spline.h.

resolve_font_path()

std::string scimesh::resolve_font_path

(

const std::string &

path

)

Turn a possibly empty font path into a path that exists.

An empty path means "use the bundled default font", see default_font_path(). Non-empty paths are returned unchanged, since the point of an explicit path is that the user chose it.

Parameters

path	Path to a .ttf file, or an empty string.

Returns

A path to an existing font file, or an empty string if path was empty and no default font could be found.

See also

default_font_path()

Definition at line 398 of file font.cpp.

rotate_mesh()

void scimesh::rotate_mesh	(	Mesh &	mesh,
		float	angle_radians,
		const Vec3 &	axis
	)

Rotate a mesh around an arbitrary axis.

Uses the right-hand rule: positive angle = counter-clockwise when looking along the axis toward the origin. Per-vertex normals (if any) are rotated with the mesh.

Parameters

[in,out]	mesh	The mesh to modify.
	angle_radians	Rotation angle in radians.
	axis	Rotation axis (does not need to be normalized).

Example

#include <cmath>
rotate_mesh(mesh, M_PI / 2.0f, Vec3(0, 1, 0));  // 90° around Y axis

See also

translate_mesh(), transform_mesh()

Definition at line 69 of file transforms.cpp.

scale_mesh() [1/2]

void scimesh::scale_mesh	(	Mesh &	mesh,
		const Vec3 &	scale
	)

Scale a mesh non-uniformly along each axis.

Multiplies each vertex position component-wise by scale. Per-vertex normals (if any) are updated as well, using the inverse transpose of the scaling matrix, so that shading stays correct for non-uniform scales.

Parameters

[in,out]	mesh	The mesh to modify.
	scale	Scale factors per axis (e.g., {2,1,1} doubles width).

Example

scale_mesh(mesh, Vec3(2.0f, 1.0f, 0.5f));  // double X, halve Z

See also

scale_mesh(Mesh&, float), rotate_mesh(), translate_mesh()

Definition at line 57 of file transforms.cpp.

scale_mesh() [2/2]

void scimesh::scale_mesh	(	Mesh &	mesh,
		float	uniform_scale
	)

Scale a mesh uniformly in all directions.

Multiplies every vertex position by uniform_scale. Per-vertex normals (if any) are updated as well; a uniform scale does not change their direction.

Parameters

[in,out]	mesh	The mesh to modify.
	uniform_scale	Scale factor (1.0 = unchanged, 2.0 = double size).

Example

scale_mesh(mesh, 0.5f);  // half size

See also

scale_mesh(Mesh&, const Vec3&)

Definition at line 65 of file transforms.cpp.

shade_pixel()

Color scimesh::shade_pixel ( const Color &  base_color, const Vec3 &  normal, const Vec3 &  light_direction, const Color &  specular_color = Color(0, 0, 0, 0), float  shininess = 0.0f  )

inline

Compute the shaded color of a pixel with a single directional light.

Uses the Blinn-Phong reflection model with ambient and diffuse terms. The ambient term prevents completely black shadows.

Parameters

base_color	The surface (unlit) color.
normal	Surface normal at this pixel (should be unit-length).
light_direction	Direction TO the light (should be unit-length).
specular_color	Specular highlight color (transparent = no specular).
shininess	Shininess exponent (higher = sharper highlights).

Returns

The final lit color.

See also

shade_pixel_multi(), Light

Definition at line 191 of file math_utils.h.

shade_pixel_multi()

Color scimesh::shade_pixel_multi ( const Color &  base_color, const Vec3 &  normal, const std::vector< Light > &  lights, float  ambient, const Color &  specular_color = Color(0, 0, 0, 0), float  shininess = 0.0f  )

inline

Compute the shaded color with multiple light sources.

Like shade_pixel(), but sums contributions from all lights in the lights array. Each light's intensity is divided by the number of lights to normalize total brightness.

Parameters

base_color	The surface (unlit) color.
normal	Surface normal (unit-length).
lights	Array of light sources.
ambient	Ambient light level (0.0–1.0).
specular_color	Specular highlight color.
shininess	Shininess exponent.

Returns

The final lit color.

See also

shade_pixel(), Light, RenderOptions::lights

Definition at line 231 of file math_utils.h.

stack_horizontal()

Image scimesh::stack_horizontal ( const std::vector< Image > &  images, FitMode  fit_mode = FitMode::PAD, const Color &  background = Color(1.0f, 1.0f, 1.0f, 1.0f)  )

inline

Stack images horizontally in a single row.

Convenience wrapper around grid_arrange() for the common case of placing images side-by-side. Equivalent to grid_arrange(images, images.size(), 1, ...).

Parameters

images	The list of images to arrange left-to-right.
fit_mode	How to handle size mismatches (PAD or SCALE).
background	Fill color for padding.

Returns

A new Image containing the horizontal strip.

See also

grid_arrange(), stack_vertical()

Definition at line 439 of file image.h.

stack_vertical()

Image scimesh::stack_vertical ( const std::vector< Image > &  images, FitMode  fit_mode = FitMode::PAD, const Color &  background = Color(1.0f, 1.0f, 1.0f, 1.0f)  )

inline

Stack images vertically in a single column.

Convenience wrapper around grid_arrange() for the common case of placing images one above the other. Equivalent to grid_arrange(images, 1, images.size(), ...).

Parameters

images	The list of images to arrange top-to-bottom.
fit_mode	How to handle size mismatches (PAD or SCALE).
background	Fill color for padding.

Returns

A new Image containing the vertical strip.

See also

grid_arrange(), stack_horizontal()

Definition at line 458 of file image.h.

str_crop()

const char * scimesh::str_crop ( CropContentDirection  d )

inline

Definition at line 43 of file to_string.h.

str_fog_space()

const char * scimesh::str_fog_space ( FogSpace  s )

inline

Definition at line 29 of file to_string.h.

str_merge()

const char * scimesh::str_merge ( MergeDirection  d )

inline

Definition at line 33 of file to_string.h.

str_plane_space()

const char * scimesh::str_plane_space ( PlaneSpace  s )

inline

Definition at line 25 of file to_string.h.

str_projection()

const char * scimesh::str_projection ( ProjectionType  p )

inline

Definition at line 17 of file to_string.h.

str_shading()

const char * scimesh::str_shading ( ShadingMode  s )

inline

Definition at line 21 of file to_string.h.

transform_direction()

Vec3 scimesh::transform_direction ( const Mat4 &  m, const Vec3 &  d  )

inline

Transform a direction vector by a 4×4 matrix (with implicit w=0).

Direction vectors use w=0 so that translation does not affect them — only rotation and scale are applied. Use for transforming normals and light directions.

Parameters

m	The transformation matrix.
d	The input direction.

Returns

The transformed direction.

See also

transform_point()

Definition at line 90 of file math_utils.h.

transform_mesh()

void scimesh::transform_mesh	(	Mesh &	mesh,
		const Mat4 &	matrix
	)

Apply an arbitrary 4×4 transformation matrix to a mesh.

Transforms all vertex positions by the matrix. This is the most general transform function — you can combine translation, rotation, and scale into a single matrix using GLM functions like glm::translate(), glm::rotate(), and glm::scale().

Per-vertex normals (if any) are transformed as well, by the inverse transpose of the upper-left 3×3 block, so that shading stays correct for shearing and non-uniform scaling. Meshes without normals are unaffected, and compute_vertex_normals() can be used to generate them.

Parameters

[in,out]	mesh	The mesh to modify.
	matrix	A 4×4 transformation matrix (column-major, GLM style).

Example

Mat4 T = glm::translate(Mat4(1.0f), Vec3(1, 0, 0));  // translate +X
Mat4 R = glm::rotate(Mat4(1.0f), M_PI/2, Vec3(0,1,0)); // rotate 90° Y
Mat4 M = T * R;  // combine: rotate, then translate
transform_mesh(mesh, M);

See also

translate_mesh(), rotate_mesh(), scale_mesh()

Definition at line 77 of file transforms.cpp.

transform_point()

Vec3 scimesh::transform_point ( const Mat4 &  m, const Vec3 &  p  )

inline

Transform a point by a 4×4 matrix (with implicit w=1).

Equivalent to (M * vec4(p, 1)).xyz. Use for transforming positions.

Parameters

m	The transformation matrix.
p	The input point.

Returns

The transformed point.

See also

transform_direction(), transform_point_homogeneous()

Definition at line 60 of file math_utils.h.

transform_point_homogeneous()

Vec4 scimesh::transform_point_homogeneous ( const Mat4 &  m, const Vec3 &  p  )

inline

Transform a point by a 4×4 matrix, returning the full Vec4 result.

Unlike transform_point(), this returns the homogeneous result (including the w component), which is needed for perspective division.

Parameters

m	The transformation matrix.
p	The input point.

Returns

The homogeneous transformed point (Vec4).

See also

transform_point(), perspective_divide()

Definition at line 75 of file math_utils.h.

translate_mesh()

void scimesh::translate_mesh	(	Mesh &	mesh,
		const Vec3 &	translation
	)

Translate (move) a mesh by a displacement vector.

Adds translation to every vertex position.

Parameters

[in,out]	mesh	The mesh to modify.
	translation	The displacement vector to add.

Example

translate_mesh(mesh, Vec3(0.0f, 5.0f, 0.0f));  // move 5 units up

See also

scale_mesh(), rotate_mesh(), transform_mesh()

Definition at line 49 of file transforms.cpp.

world_to_screen()

ProjectedPoint scimesh::world_to_screen	(	const Camera &	camera,
		const Vec3 &	world,
		int	width,
		int	height,
		ProjectionType	projection,
		float	near_plane,
		float	far_plane
	)

Project a world-space point to the pixel coordinates of a rendered image.

Uses exactly the same view and projection matrices as the renderer, so the result matches the rendered image (of size width x height). This is what makes it possible to anchor 2D annotations to locations in the 3D scene — for example a TextLayer in TextSpace::SCREEN placed next to a rendered object, or a callout line drawn with a LineLayer.

Parameters

camera	The camera the render used.
world	The point to project, in world space.
width	Width of the rendered image in pixels.
height	Height of the rendered image in pixels.
projection	Projection type the render used. Note that this is RenderOptions::projection, which the renderer applies instead of Camera::projection.
near_plane	Near clipping plane distance of the render.
far_plane	Far clipping plane distance of the render.

Returns

The projected point, see ProjectedPoint.

Exceptions

std::invalid_argument

If width or height is not positive.

Example

ProjectedPoint p = world_to_screen(cam, Vec3(0, 0, 0), 800, 600,
                             ProjectionType::PERSPECTIVE, 0.1f, 100.0f);
if (p.in_front) {
    std::printf("origin at (%.1f, %.1f), depth %.3f\n", p.pixel.x, p.pixel.y, p.depth);
}

See also

ProjectedPoint, TextLayer, Camera::get_view_matrix()

Definition at line 39 of file camera.cpp.

Variable Documentation

DEFAULT_COLOR

constexpr Color scimesh::DEFAULT_COLOR {0.7f, 0.7f, 0.7f, 1.0f}

constexpr

The default mesh color: a neutral light gray (0.7, 0.7, 0.7).

Used when no explicit color is assigned to a mesh.

See also

Color, Mesh::default_color

Definition at line 144 of file types.h.

TRANSPARENT_BLACK

constexpr Color scimesh::TRANSPARENT_BLACK {0.0f, 0.0f, 0.0f, 0.0f}

constexpr

A fully transparent black color (0, 0, 0, 0).

Convenience constant for transparent backgrounds or clearing.

See also

Color

Definition at line 150 of file types.h.

WHITE

constexpr Color scimesh::WHITE {1.0f, 1.0f, 1.0f, 1.0f}

constexpr

An opaque white color (1, 1, 1, 1).

Convenience constant for backgrounds.

See also

Color

Definition at line 156 of file types.h.