xiuminglib.io package

Submodules

xiuminglib.io.exr module

xiuminglib.io.exr.read(path)[source]

Reads a non-multi-layer OpenEXR image from disk.

Reading a multi-layer OpenEXR cannot be done with OpenCV and would require installing OpenEXR and Imath (see cli/exr2npz.py).

Parameters:path (str) – Path to the .exr file.
Returns:Loaded (float) array with RGB channels in order.
Return type:numpy.ndarray

xiuminglib.io.hdr module

xiuminglib.io.hdr.read(path)[source]

Reads an HDR map from disk.

Parameters:path (str) – Path to the .hdr file.
Returns:Loaded (float) HDR map with RGB channels in order.
Return type:numpy.ndarray
xiuminglib.io.hdr.write(rgb, outpath)[source]

Writes a float32 array as an HDR map to disk.

Parameters:
Writes
  • The resultant HDR map.

xiuminglib.io.img module

xiuminglib.io.img.load(*args, **kwargs)[source]

Alias for read(), mostly for backward compatibility.

TODO: remove

xiuminglib.io.img.read(path, auto_rotate=False)[source]

Reads an image from disk.

Parameters:
  • path (str) – Path to the image file. Supported formats: whatever Pillow supports.
  • auto_rotate (bool, optional) – Whether to auto-rotate the read image array according to its EXIF orientation, if any.
Returns:

Loaded image.

Return type:

numpy.ndarray

xiuminglib.io.img.write_arr(*args, **kwargs)[source]

Alias for write_float(), mostly for backward compatibility.

TODO: remove

xiuminglib.io.img.write_float(arr_0to1, outpath, img_dtype='uint8', clip=False)[source]

Writes a float array as an image to disk.

Parameters:
  • arr_0to1 (numpy.ndarray) – Array with values roughly \(\in [0,1]\).
  • outpath (str) – Output path.
  • img_dtype (str, optional) – Image data type. Defaults to 'uint8'.
  • clip (bool, optional) – Whether to clip values to \([0,1]\). Defaults to False.
Writes
  • The resultant image.
Returns:The resultant image array.
Return type:numpy.ndarray
xiuminglib.io.img.write_img(*args, **kwargs)[source]

Alias for write_uint(), mostly for backward compatibility.

TODO: remove

xiuminglib.io.img.write_uint(arr_uint, outpath)[source]

Writes an uint array as an image to disk.

Parameters:
Writes
  • The resultant image.

xiuminglib.io.json module

xiuminglib.io.json.read(path)[source]

Reads a JSON.

Parameters:path (str) – Path to the JSON file.
Returns:Data dictionary.
xiuminglib.io.json.write(dict_, path)[source]

Writes a dictionary into a JSON.

Parameters:
  • dict (dict) – Data dictionary.
  • path (str) – Path to the JSON file.
Writes
  • JSON file.

xiuminglib.io.np module

xiuminglib.io.np.read_or_write(data_f, fallback=None)[source]

Loads the data file if it exists. Otherwise, if fallback is provided, call fallback and save its return to disk.

Parameters:
  • data_f (str) – Path to the data file, whose extension will be used for deciding how to load the data.
  • fallback (function, optional) –

    Fallback function used if data file doesn’t exist. Its return will be saved to data_f for future loadings. It should not take arguments, but if yours requires taking arguments, just wrap yours with:

    fallback=lambda: your_fancy_func(var0, var1)
    
Returns:

Data loaded if data_f exists; otherwise, fallback’s return (None if no fallback).

Writes
  • Return by the fallback, if provided.

xiuminglib.io.objmtl module

class xiuminglib.io.objmtl.Mtl(obj, Ns=96.078431, Ka=(1, 1, 1), Kd=(0.64, 0.64, 0.64), Ks=(0.5, 0.5, 0.5), Ni=1, d=1, illum=2)[source]

Bases: object

Wavefront .mtl object.

mtlfile

Material file name, set to obj.mtllib.

Type:str
newmtl

Material name, set to obj.usemtl.

Type:str
map_Kd_path

Path to the diffuse map, set to obj.diffuse_map_path.

Type:str
map_Kd_scale

Scale of the diffuse map, set to obj.diffuse_map_scale.

Type:float
Ns
Type:float
Ka
Type:tuple
Kd
Type:tuple
Ks
Type:tuple
Ni
Type:float
d
Type:float
illum
Type:int
__init__(obj, Ns=96.078431, Ka=(1, 1, 1), Kd=(0.64, 0.64, 0.64), Ks=(0.5, 0.5, 0.5), Ni=1, d=1, illum=2)[source]
Parameters:
  • obj (Obj) – Obj object for which this Mtl object is created.
  • Ns (float, optional) – Specular exponent, normally \(\in[0, 1000]\).
  • Ka (tuple, optional) – Ambient reflectivity, each float normally \(\in[0, 1]\). Values outside increase or decrease relectivity accordingly.
  • Kd (tuple, optional) – Diffuse reflectivity. Same range as Ka.
  • Ks (tuple, optional) – Specular reflectivity. Same range as Ka.
  • Ni (float, optional) – Optical density, a.k.a. index of refraction \(\in[0.001, 10]\). 1 means light doesn’t bend as it passes through. Increasing it increases the amount of bending. Glass has an index of refraction of about 1.5. Values of less than 1.0 produce bizarre results and are not recommended.
  • d (float, optional) – Amount this material dissolves into the background \(\in[0, 1]\). 1.0 is fully opaque (default), and 0 is fully dissolved (completely transparent). Unlike a real transparent material, the dissolve does not depend upon material thickness, nor does it have any spectral character. Dissolve works on all illumination models.
  • illum (int, optional) – Illumination model \(\in[0, 1, ..., 10]\).
print_info()[source]
write_file(outdir)[source]

Unit tests that can also serve as example usage.

Parameters:outdir (str) – Output directory.
Writes
  • Output .mtl file.
class xiuminglib.io.objmtl.Obj(o=None, v=None, f=None, vn=None, fn=None, vt=None, ft=None, s=False, mtllib=None, usemtl=None, diffuse_map_path=None, diffuse_map_scale=1)[source]

Bases: object

Wavefront .obj Object.

Face, vertex, or other indices here all start from 1.

o
Type:str
v
Type:numpy.ndarray
f
Type:list
vn
Type:numpy.ndarray
fn
Type:list
vt
Type:numpy.ndarray
ft
Type:list
s
Type:bool
mtllib
Type:str
usemtl
Type:str
diffuse_map_path
Type:str
diffuse_map_scale
Type:float
__init__(o=None, v=None, f=None, vn=None, fn=None, vt=None, ft=None, s=False, mtllib=None, usemtl=None, diffuse_map_path=None, diffuse_map_scale=1)[source]
Parameters:
  • o (str, optional) – Object name.
  • v (numpy.ndarray, optional) – Vertex coordinates.
  • f (list, optional) – Faces’ vertex indices (1-indexed), e.g., [[1, 2, 3], [4, 5, 6], [7, 8, 9, 10], ...].
  • vn (numpy.ndarray, optional) – Vertex normals of shape N-by-3, normalized or not.
  • fn (list, optional) – Faces’ vertex normal indices, e.g., [[1, 1, 1], [], [2, 2, 2, 2], ...]. Must be of the same length as f.
  • vt (numpy.ndarray, optional) – Vertex texture coordinates of shape N-by-2. Coordinates must be normalized to \([0, 1]\).
  • ft (list, optional) – Faces’ texture vertex indices, e.g., [[1, 2, 3], [4, 5, 6], [], ...]. Must be of the same length as f.
  • s (bool, optional) – Group smoothing.
  • mtllib (str, optional) – Material file name, e.g., 'cube.mtl'.
  • usemtl (str, optional) – Material name (defined in .mtl file).
  • diffuse_map_path (str, optional) – Path to diffuse texture map.
  • diffuse_map_scale (float, optional) – Scale of diffuse texture map.
load_file(obj_file)[source]

Loads a (basic) .obj file as an object.

Populates attributes with contents read from file.

Parameters:obj_file (str) – Path to .obj file.
print_info()[source]
set_face_normals()[source]

Sets face normals according to geometric vertices and their orders in forming faces.

Returns:
  • vn (numpy.ndarray) – Normal vectors.
  • fn (list) – Normal faces. Each member list consists of the same integer, e.g., [[1, 1, 1], [2, 2, 2, 2], ...].
Return type:tuple
write_file(objpath)[source]

Writes the current model to a .obj file.

Parameters:objpath (str) – Path to the output .obj.
Writes
  • Output .obj file.
xiuminglib.io.objmtl.main()[source]

Unit tests that can also serve as example usage.