add documention workflow
This commit is contained in:
AndreaRigoni
373
docs/python/usage.md
Normal file
373
docs/python/usage.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# Python API Usage
|
||||
|
||||
The `uLib` Python package is split into two sub-modules mirroring the C++ library:
|
||||
|
||||
| Sub-module | Contents |
|
||||
|---|---|
|
||||
| `uLib.Core` | Low-level utilities: `Object`, `Timer`, `Options`, `TypeRegister` |
|
||||
| `uLib.Math` | Geometry, grids, voxel images, ray-tracing, image filters |
|
||||
|
||||
```python
|
||||
import uLib
|
||||
# Sub-modules are accessible as attributes
|
||||
uLib.Core # core utilities
|
||||
uLib.Math # mathematical structures
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Core
|
||||
|
||||
### Object
|
||||
|
||||
Base class for uLib objects; exposed to Python for type-hierarchy purposes.
|
||||
|
||||
```python
|
||||
obj = uLib.Core.Object()
|
||||
copy = obj.DeepCopy()
|
||||
```
|
||||
|
||||
### Timer
|
||||
|
||||
Precision wall-clock timer.
|
||||
|
||||
```python
|
||||
import time
|
||||
timer = uLib.Core.Timer()
|
||||
timer.Start()
|
||||
time.sleep(0.5)
|
||||
elapsed = timer.StopWatch() # returns elapsed seconds as float
|
||||
print(f"Elapsed: {elapsed:.3f} s")
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
Wraps Boost.ProgramOptions for INI-style configuration files.
|
||||
|
||||
```python
|
||||
opt = uLib.Core.Options("My Program")
|
||||
opt.parse_config_file("config.ini") # load settings
|
||||
n = opt.count("my_key") # check if key exists
|
||||
opt.save_config_file("out.ini")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – Linear Algebra
|
||||
|
||||
The math module exposes Eigen3 vectors and matrices as well-typed Python objects with NumPy interoperability.
|
||||
|
||||
### Fixed-size Vectors
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import uLib
|
||||
|
||||
# Construct from list
|
||||
v3 = uLib.Math.Vector3f([1.0, 2.0, 3.0])
|
||||
print(v3[0], v3[1], v3[2]) # 1.0 2.0 3.0
|
||||
|
||||
# Construct from NumPy array
|
||||
arr = np.array([4.0, 5.0, 6.0], dtype=np.float32)
|
||||
v3b = uLib.Math.Vector3f(arr)
|
||||
|
||||
# Zero-initialise
|
||||
v4d = uLib.Math.Vector4d() # all zeros
|
||||
|
||||
# Available types
|
||||
# Vector1f / 2f / 3f / 4f (float32)
|
||||
# Vector1d / 2d / 3d / 4d (float64)
|
||||
# Vector1i / 2i / 3i / 4i (int32)
|
||||
```
|
||||
|
||||
### Fixed-size Matrices
|
||||
|
||||
```python
|
||||
# 2-by-2 float matrix
|
||||
m2f = uLib.Math.Matrix2f()
|
||||
m2f[0, 0] = 1; m2f[0, 1] = 2
|
||||
m2f[1, 0] = 3; m2f[1, 1] = 4
|
||||
|
||||
# From list (row-major)
|
||||
m4f = uLib.Math.Matrix4f([1,0,0,0, 0,1,0,0, 0,0,1,0, 0,0,0,1])
|
||||
|
||||
# From NumPy (2-D array)
|
||||
mat = np.eye(3, dtype=np.float32)
|
||||
m3f = uLib.Math.Matrix3f(mat)
|
||||
|
||||
# Dynamic matrices
|
||||
mXf = uLib.Math.MatrixXf(4, 4) # 4×4 float, zeros
|
||||
```
|
||||
|
||||
### Homogeneous Types
|
||||
|
||||
```python
|
||||
# HPoint3f – a 3-D point in homogeneous coordinates (w = 1)
|
||||
p = uLib.Math.HPoint3f(1.0, 2.0, 3.0)
|
||||
|
||||
# HVector3f – a free vector (w = 0)
|
||||
v = uLib.Math.HVector3f(0.0, 1.0, 0.0)
|
||||
|
||||
# HLine3f – a parametric ray
|
||||
line = uLib.Math.HLine3f()
|
||||
line.origin = uLib.Math.HPoint3f(0, 0, 0)
|
||||
line.direction = uLib.Math.HVector3f(0, 0, 1)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – Transforms and Geometry
|
||||
|
||||
### AffineTransform
|
||||
|
||||
A rigid-body / affine transform stored as a 4×4 matrix.
|
||||
|
||||
```python
|
||||
tf = uLib.Math.AffineTransform()
|
||||
|
||||
tf.SetPosition([1.0, 0.0, 0.0]) # translate
|
||||
tf.Translate([0.0, 1.0, 0.0]) # cumulative translate
|
||||
tf.Scale([2.0, 2.0, 2.0]) # uniform scale
|
||||
tf.Rotate(uLib.Math.Vector3f([0, 0, 3.14159])) # Euler angles (rad)
|
||||
|
||||
mat4 = tf.GetWorldMatrix() # 4×4 matrix
|
||||
pos = tf.GetPosition() # Vector3f
|
||||
```
|
||||
|
||||
### Geometry
|
||||
|
||||
Inherits `AffineTransform`; converts points between world and local frames.
|
||||
|
||||
```python
|
||||
geo = uLib.Math.Geometry()
|
||||
geo.SetPosition([1.0, 1.0, 1.0])
|
||||
|
||||
world_pt = uLib.Math.Vector4f([2.0, 3.0, 2.0, 1.0])
|
||||
local_pt = geo.GetLocalPoint(world_pt)
|
||||
back = geo.GetWorldPoint(local_pt)
|
||||
# back ≈ [2, 3, 2, 1]
|
||||
```
|
||||
|
||||
### ContainerBox
|
||||
|
||||
An axis-aligned bounding box with an associated transform.
|
||||
|
||||
```python
|
||||
box = uLib.Math.ContainerBox()
|
||||
box.SetOrigin([-1.0, -1.0, -1.0])
|
||||
box.SetSize([2.0, 2.0, 2.0])
|
||||
print(box.GetSize()) # [2, 2, 2]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – Structured Grids
|
||||
|
||||
### StructuredGrid (3-D)
|
||||
|
||||
A 3-D voxel grid (origin, spacing, and integer dimensions).
|
||||
|
||||
```python
|
||||
dims = uLib.Math.Vector3i([10, 10, 10])
|
||||
grid = uLib.Math.StructuredGrid(dims)
|
||||
grid.SetSpacing([1.0, 1.0, 1.0])
|
||||
grid.SetOrigin([0.0, 0.0, 0.0])
|
||||
|
||||
print(grid.GetSpacing()) # [1, 1, 1]
|
||||
print(grid.IsInsideBounds([5, 5, 5, 1])) # True
|
||||
idx = grid.Find([2.5, 2.5, 2.5]) # returns grid cell index
|
||||
```
|
||||
|
||||
### Structured2DGrid / Structured4DGrid
|
||||
|
||||
```python
|
||||
grid2d = uLib.Math.Structured2DGrid()
|
||||
grid2d.SetDims([100, 100])
|
||||
grid2d.SetPhysicalSpace([0, 0], [1, 1])
|
||||
print(grid2d.GetSpacing())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – VoxImage
|
||||
|
||||
`VoxImage` is a 3-D voxel volume where each cell stores a `Voxel` ( `.Value` + `.Count`).
|
||||
|
||||
```python
|
||||
dims = uLib.Math.Vector3i([20, 20, 20])
|
||||
img = uLib.Math.VoxImage(dims)
|
||||
img.SetSpacing([0.5, 0.5, 0.5])
|
||||
|
||||
# Access by linear index
|
||||
img.SetValue(0, 42.0)
|
||||
print(img.GetValue(0)) # 42.0
|
||||
|
||||
# Access by 3-D index
|
||||
img.SetValue(uLib.Math.Vector3i([1, 1, 1]), 7.5)
|
||||
print(img.GetValue(uLib.Math.Vector3i([1, 1, 1]))) # 7.5
|
||||
|
||||
# Clipping / masking helpers
|
||||
cropped = img.clipImage(uLib.Math.Vector3i([2, 2, 2]),
|
||||
uLib.Math.Vector3i([18, 18, 18]))
|
||||
masked = img.maskImage(0.0, 100.0, 0.0) # mask outside [0, 100]
|
||||
|
||||
# I/O
|
||||
img.ExportToVti("output.vti")
|
||||
img.ImportFromVti("output.vti")
|
||||
```
|
||||
|
||||
### Voxel (element type)
|
||||
|
||||
```python
|
||||
vox = uLib.Math.Voxel()
|
||||
vox.Value = 1.5
|
||||
vox.Count = 3
|
||||
|
||||
data = img.Data() # returns the underlying Vector_Voxel
|
||||
vox0 = data[0]
|
||||
print(vox0.Value, vox0.Count)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – VoxRaytracer
|
||||
|
||||
Performs ray-tracing through a `StructuredGrid` and returns per-voxel chord lengths.
|
||||
|
||||
```python
|
||||
import numpy as np
|
||||
import uLib
|
||||
|
||||
grid = uLib.Math.StructuredGrid([10, 10, 10])
|
||||
grid.SetSpacing([1.0, 1.0, 1.0])
|
||||
grid.SetOrigin([0.0, 0.0, 0.0])
|
||||
|
||||
rt = uLib.Math.VoxRaytracer(grid)
|
||||
|
||||
# Trace a ray between two homogeneous points (x, y, z, w=1)
|
||||
p1 = np.array([0.5, 0.5, -1.0, 1.0], dtype=np.float32)
|
||||
p2 = np.array([0.5, 0.5, 11.0, 1.0], dtype=np.float32)
|
||||
result = rt.TraceBetweenPoints(p1, p2)
|
||||
|
||||
print("Voxels crossed:", result.Count())
|
||||
print("Total length :", result.TotalLength())
|
||||
|
||||
elements = result.Data()
|
||||
for i in range(result.Count()):
|
||||
print(f" vox_id={elements[i].vox_id} L={elements[i].L:.4f}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – Image Filters
|
||||
|
||||
All filters share the same interface: construct with a kernel size, attach a `VoxImage`, optionally set parameters, then call `.Run()`.
|
||||
|
||||
```python
|
||||
import uLib
|
||||
|
||||
dims = uLib.Math.Vector3i([10, 10, 10])
|
||||
img = uLib.Math.VoxImage(dims)
|
||||
for i in range(10**3):
|
||||
img.SetValue(i, float(i))
|
||||
|
||||
kernel_dims = uLib.Math.Vector3i([3, 3, 3])
|
||||
```
|
||||
|
||||
### Linear (Gaussian / Box) Filter
|
||||
|
||||
```python
|
||||
filt = uLib.Math.VoxFilterAlgorithmLinear(kernel_dims)
|
||||
filt.SetImage(img)
|
||||
filt.SetKernelNumericXZY([1.0] * 27) # uniform box kernel, length = product of dims
|
||||
filt.Run()
|
||||
```
|
||||
|
||||
### ABTrim Filter
|
||||
|
||||
Applies alpha-beta trimming to remove outliers before averaging.
|
||||
|
||||
```python
|
||||
filt = uLib.Math.VoxFilterAlgorithmAbtrim(kernel_dims)
|
||||
filt.SetImage(img)
|
||||
filt.SetKernelNumericXZY([1.0] * 27)
|
||||
filt.SetABTrim(2, 2) # trim 2 low and 2 high values
|
||||
filt.Run()
|
||||
```
|
||||
|
||||
### Bilateral Filter
|
||||
|
||||
Edge-preserving smoothing controlled by a spatial sigma (from the kernel shape) and an intensity sigma.
|
||||
|
||||
```python
|
||||
filt = uLib.Math.VoxFilterAlgorithmBilateral(kernel_dims)
|
||||
filt.SetImage(img)
|
||||
filt.SetKernelNumericXZY([1.0] * 27)
|
||||
filt.SetIntensitySigma(0.3)
|
||||
filt.Run()
|
||||
```
|
||||
|
||||
### Threshold Filter
|
||||
|
||||
Zeros voxels below a threshold.
|
||||
|
||||
```python
|
||||
filt = uLib.Math.VoxFilterAlgorithmThreshold(kernel_dims)
|
||||
filt.SetImage(img)
|
||||
filt.SetKernelNumericXZY([1.0] * 27)
|
||||
filt.SetThreshold(0.5)
|
||||
filt.Run()
|
||||
```
|
||||
|
||||
### Median Filter
|
||||
|
||||
```python
|
||||
filt = uLib.Math.VoxFilterAlgorithmMedian(kernel_dims)
|
||||
filt.SetImage(img)
|
||||
filt.SetKernelNumericXZY([1.0] * 27)
|
||||
filt.Run()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## uLib.Math – Accumulators
|
||||
|
||||
Accumulators collect scalar samples and return a summary statistic.
|
||||
|
||||
```python
|
||||
# Arithmetic mean
|
||||
acc = uLib.Math.Accumulator_Mean_f()
|
||||
acc(10.0)
|
||||
acc(20.0)
|
||||
mean = acc() # 15.0
|
||||
|
||||
# Alpha-beta trimmed mean
|
||||
acc2 = uLib.Math.Accumulator_ABTrim_f()
|
||||
acc2.SetABTrim(0.1, 0.1) # trim bottom 10 % and top 10 %
|
||||
acc2 += 1.0
|
||||
acc2 += 9999.0 # outlier
|
||||
acc2 += 5.0
|
||||
result = acc2() # trimmed mean ≈ 3.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Vectors (`uLib.Math.Vector_*`)
|
||||
|
||||
Typed dynamic arrays backed by `uLib::Vector<T>` with optional CUDA memory management.
|
||||
|
||||
```python
|
||||
# Integer vector
|
||||
vi = uLib.Math.Vector_i()
|
||||
vi.append(1); vi.append(2); vi.append(3)
|
||||
print(len(vi), vi[0])
|
||||
|
||||
# Float vector with CUDA management
|
||||
vf = uLib.Math.Vector_f()
|
||||
vf.append(1.5)
|
||||
vf.MoveToVRAM() # copy to GPU (no-op when CUDA is absent)
|
||||
vf.MoveToRAM() # copy back to CPU
|
||||
|
||||
# Other types: Vector_ui, Vector_l, Vector_ul, Vector_d
|
||||
# Compound element types: Vector_Vector3f, Vector_Vector4f, Vector_Voxel …
|
||||
```
|
||||
Reference in New Issue
Block a user