Debian Codegraph @

pyvista/plotting/utilities/cubemap.py

raw
1 """Cubemap utilities."""
2
3 from __future__ import annotations
4
5 from pathlib import Path
6
7 import pyvista as pv
8
9
10 def cubemap(path='', prefix='', ext='.jpg'):
11 """Construct a cubemap from 6 images from a directory.
12
13 Each of the 6 images must be in the following format:
14
15 - <prefix>negx<ext>
16 - <prefix>negy<ext>
17 - <prefix>negz<ext>
18 - <prefix>posx<ext>
19 - <prefix>posy<ext>
20 - <prefix>posz<ext>
21
22 Prefix may be empty, and extension will default to ``'.jpg'``
23
24 For example, if you have 6 images with the skybox2 prefix:
25
26 - ``'skybox2-negx.jpg'``
27 - ``'skybox2-negy.jpg'``
28 - ``'skybox2-negz.jpg'``
29 - ``'skybox2-posx.jpg'``
30 - ``'skybox2-posy.jpg'``
31 - ``'skybox2-posz.jpg'``
32
33 Parameters
34 ----------
35 path : str, default: ""
36 Directory containing the cubemap images.
37
38 prefix : str, default: ""
39 Prefix to the filename.
40
41 ext : str, default: ".jpg"
42 The filename extension. For example ``'.jpg'``.
43
44 Returns
45 -------
46 pyvista.Texture
47 Texture with cubemap.
48
49 Notes
50 -----
51 Cubemap will appear flipped relative to the XY plane between VTK v9.1 and
52 VTK v9.2.
53
54 Examples
55 --------
56 Load a skybox given a directory, prefix, and file extension.
57
58 >>> import pyvista as pv
59 >>> skybox = pv.cubemap('my_directory', 'skybox', '.jpeg') # doctest:+SKIP
60
61 """
62 sets = ['posx', 'negx', 'posy', 'negy', 'posz', 'negz']
63 image_paths = [str(Path(path) / f'{prefix}{suffix}{ext}') for suffix in sets]
64 return _cubemap_from_paths(image_paths)
65
66
67 def cubemap_from_filenames(image_paths):
68 """Construct a cubemap from 6 images.
69
70 Images must be in the following order:
71
72 - Positive X
73 - Negative X
74 - Positive Y
75 - Negative Y
76 - Positive Z
77 - Negative Z
78
79 Parameters
80 ----------
81 image_paths : sequence[str]
82 Paths of the individual cubemap images.
83
84 Returns
85 -------
86 pyvista.Texture
87 Texture with cubemap.
88
89 Examples
90 --------
91 Load a skybox given a list of image paths.
92
93 >>> image_paths = [
94 ... '/home/user/_px.jpg',
95 ... '/home/user/_nx.jpg',
96 ... '/home/user/_py.jpg',
97 ... '/home/user/_ny.jpg',
98 ... '/home/user/_pz.jpg',
99 ... '/home/user/_nz.jpg',
100 ... ]
101 >>> skybox = pv.cubemap(image_paths=image_paths) # doctest:+SKIP
102
103 """
104 if len(image_paths) != 6:
105 msg = 'image_paths must contain 6 paths'
106 raise ValueError(msg)
107
108 return _cubemap_from_paths(image_paths)
109
110
111 def _cubemap_from_paths(image_paths):
112 """Construct a cubemap from image paths."""
113 for image_path in image_paths:
114 if not Path(image_path).is_file():
115 file_str = '\n'.join(image_paths)
116 msg = (
117 f'Unable to locate {image_path}\nExpected to find the following files:\n{file_str}'
118 )
119 raise FileNotFoundError(msg)
120
121 texture = pv.Texture() # type: ignore[abstract]
122 texture.mipmap = True
123 texture.interpolate = True
124 texture.color_mode = 'direct'
125 texture.cube_map = True # Must be set prior to setting images
126
127 # add each image to the cubemap
128 for i, fn in enumerate(image_paths):
129 # Read and flip along y-axis
130 texture.SetInputDataObject(i, pv.read(fn, cls=pv.ImageData)._flip_uniform(1))
131
132 return texture