Debian Codegraph @

pyvista/examples/planets.py

raw
1 """Downloadable datasets of 3D Celestial Bodies."""
2
3 from __future__ import annotations
4
5 import numpy as np
6
7 import pyvista as pv
8 from pyvista._deprecate_positional_args import _deprecate_positional_args
9 from pyvista.examples._dataset_loader import _download_dataset
10 from pyvista.examples._dataset_loader import _SingleFileDownloadableDatasetLoader
11
12
13 def _download_dataset_texture(
14 loader: _SingleFileDownloadableDatasetLoader, *, load: bool, texture: bool
15 ):
16 dataset = _download_dataset(loader, load=load)
17 if texture:
18 from pyvista.plotting.texture import Texture # noqa: PLC0415
19
20 return Texture(dataset) # type: ignore[abstract]
21 return dataset
22
23
24 def _sphere_with_texture_map(radius=1.0, lat_resolution=50, lon_resolution=100):
25 """Sphere with texture coordinates.
26
27 Parameters
28 ----------
29 radius : float, default: 1.0
30 Sphere radius.
31
32 lat_resolution : int, default: 100
33 Set the number of points in the latitude direction.
34
35 lon_resolution : int, default: 100
36 Set the number of points in the longitude direction.
37
38 Returns
39 -------
40 pyvista.PolyData
41 Sphere mesh with texture coordinates.
42
43 """
44 # https://github.com/pyvista/pyvista/pull/2994#issuecomment-1200520035
45 theta, phi = np.mgrid[0 : np.pi : lat_resolution * 1j, 0 : 2 * np.pi : lon_resolution * 1j] # type: ignore[misc]
46 x = radius * np.sin(theta) * np.cos(phi)
47 y = radius * np.sin(theta) * np.sin(phi)
48 z = radius * np.cos(theta)
49 sphere = pv.StructuredGrid(x, y, z)
50 texture_coords = np.empty((sphere.n_points, 2))
51 texture_coords[:, 0] = phi.ravel('F') / phi.max()
52 texture_coords[:, 1] = theta[::-1, :].ravel('F') / theta.max()
53 sphere.active_texture_coordinates = texture_coords
54 return sphere.extract_surface(algorithm=None, pass_pointid=False, pass_cellid=False)
55
56
57 @_deprecate_positional_args
58 def load_sun(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
59 """Load the Sun as a textured sphere.
60
61 Parameters
62 ----------
63 radius : float, default: 1.0
64 Sphere radius.
65
66 lat_resolution : int, default: 50
67 Set the number of points in the latitude direction.
68
69 lon_resolution : int, default: 100
70 Set the number of points in the longitude direction.
71
72 Returns
73 -------
74 pyvista.PolyData
75 Sun dataset.
76
77 Examples
78 --------
79 >>> import pyvista as pv
80 >>> from pyvista import examples
81 >>> mesh = examples.planets.load_sun()
82 >>> texture = examples.planets.download_sun_surface(texture=True)
83 >>> image_path = examples.planets.download_stars_sky_background(load=False)
84 >>> mesh.plot(texture=texture, background=image_path)
85
86 .. seealso::
87
88 :func:`~pyvista.examples.planets.download_sun_surface`
89 Download the surface of the Sun.
90
91 :ref:`planets_example`
92 Example plot of the solar system.
93
94 """
95 return _sphere_with_texture_map(
96 radius=radius,
97 lat_resolution=lat_resolution,
98 lon_resolution=lon_resolution,
99 )
100
101
102 @_deprecate_positional_args
103 def load_moon(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
104 """Load the Moon as a textured sphere.
105
106 Parameters
107 ----------
108 radius : float, default: 1.0
109 Sphere radius.
110
111 lat_resolution : int, default: 50
112 Set the number of points in the latitude direction.
113
114 lon_resolution : int, default: 100
115 Set the number of points in the longitude direction.
116
117 Returns
118 -------
119 pyvista.PolyData
120 Moon dataset.
121
122 Examples
123 --------
124 >>> import pyvista as pv
125 >>> from pyvista import examples
126 >>> mesh = examples.planets.load_moon()
127 >>> texture = examples.planets.download_moon_surface(texture=True)
128 >>> image_path = examples.planets.download_stars_sky_background(load=False)
129 >>> mesh.plot(texture=texture, background=image_path)
130
131 .. seealso::
132
133 :func:`~pyvista.examples.planets.download_moon_surface`
134 Download the surface of the Moon.
135
136 :ref:`planets_example`
137 Example plot of the solar system.
138
139 """
140 return _sphere_with_texture_map(
141 radius=radius,
142 lat_resolution=lat_resolution,
143 lon_resolution=lon_resolution,
144 )
145
146
147 @_deprecate_positional_args
148 def load_mercury(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
149 """Load the planet Mercury as a textured sphere.
150
151 Parameters
152 ----------
153 radius : float, default: 1.0
154 Sphere radius.
155
156 lat_resolution : int, default: 50
157 Set the number of points in the latitude direction.
158
159 lon_resolution : int, default: 100
160 Set the number of points in the longitude direction.
161
162 Returns
163 -------
164 pyvista.PolyData
165 Mercury dataset.
166
167 Examples
168 --------
169 >>> import pyvista as pv
170 >>> from pyvista import examples
171 >>> mesh = examples.planets.load_mercury()
172 >>> texture = examples.planets.download_mercury_surface(texture=True)
173 >>> image_path = examples.planets.download_stars_sky_background(load=False)
174 >>> mesh.plot(texture=texture, background=image_path)
175
176 .. seealso::
177
178 :func:`~pyvista.examples.planets.download_mercury_surface`
179 Download the surface of Mercury.
180
181 :ref:`planets_example`
182 Example plot of the solar system.
183
184 """
185 return _sphere_with_texture_map(
186 radius=radius,
187 lat_resolution=lat_resolution,
188 lon_resolution=lon_resolution,
189 )
190
191
192 @_deprecate_positional_args
193 def load_venus(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
194 """Load the planet Venus as a textured sphere.
195
196 Parameters
197 ----------
198 radius : float, default: 1.0
199 Sphere radius.
200
201 lat_resolution : int, default: 50
202 Set the number of points in the latitude direction.
203
204 lon_resolution : int, default: 100
205 Set the number of points in the longitude direction.
206
207 Returns
208 -------
209 pyvista.PolyData
210 Venus dataset.
211
212 Examples
213 --------
214 >>> import pyvista as pv
215 >>> from pyvista import examples
216 >>> mesh = examples.planets.load_venus()
217 >>> texture = examples.planets.download_venus_surface(texture=True)
218 >>> image_path = examples.planets.download_stars_sky_background(load=False)
219 >>> mesh.plot(texture=texture, background=image_path)
220
221 .. seealso::
222
223 :func:`~pyvista.examples.planets.download_venus_surface`
224 Download the surface of the Venus.
225
226 :ref:`planets_example`
227 Example plot of the solar system.
228
229 """
230 return _sphere_with_texture_map(
231 radius=radius,
232 lat_resolution=lat_resolution,
233 lon_resolution=lon_resolution,
234 )
235
236
237 @_deprecate_positional_args
238 def load_earth(radius=1.0, lat_resolution=50, lon_resolution=100):
239 """Load the planet Earth as a textured sphere.
240
241 Parameters
242 ----------
243 radius : float, default: 1.0
244 Sphere radius.
245
246 lat_resolution : int, default: 50
247 Set the number of points in the latitude direction.
248
249 lon_resolution : int, default: 100
250 Set the number of points in the longitude direction.
251
252 Returns
253 -------
254 pyvista.PolyData
255 Earth dataset.
256
257 Examples
258 --------
259 >>> import pyvista as pv
260 >>> from pyvista import examples
261 >>> mesh = examples.planets.load_earth()
262 >>> texture = examples.load_globe_texture()
263 >>> image_path = examples.planets.download_stars_sky_background(load=False)
264 >>> mesh.plot(texture=texture, background=image_path)
265
266 .. seealso::
267
268 :func:`~pyvista.examples.examples.load_globe_texture`
269 Download the surface of the Earth.
270
271 :ref:`planets_example`
272 Example plot of the solar system.
273
274 """
275 return _sphere_with_texture_map(
276 radius=radius,
277 lat_resolution=lat_resolution,
278 lon_resolution=lon_resolution,
279 )
280
281
282 @_deprecate_positional_args
283 def load_mars(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
284 """Load the planet Mars as a textured Sphere.
285
286 Parameters
287 ----------
288 radius : float, default: 1.0
289 Sphere radius.
290
291 lat_resolution : int, default: 50
292 Set the number of points in the latitude direction.
293
294 lon_resolution : int, default: 100
295 Set the number of points in the longitude direction.
296
297 Returns
298 -------
299 pyvista.PolyData
300 Mars dataset.
301
302 Examples
303 --------
304 >>> import pyvista as pv
305 >>> from pyvista import examples
306 >>> mesh = examples.planets.load_mars()
307 >>> texture = examples.planets.download_mars_surface(texture=True)
308 >>> image_path = examples.planets.download_stars_sky_background(load=False)
309 >>> mesh.plot(texture=texture, background=image_path)
310
311 .. seealso::
312
313 :func:`~pyvista.examples.planets.download_mars_surface`
314 Download the surface of Mars.
315
316 :ref:`planets_example`
317 Example plot of the solar system.
318
319 """
320 return _sphere_with_texture_map(
321 radius=radius,
322 lat_resolution=lat_resolution,
323 lon_resolution=lon_resolution,
324 )
325
326
327 @_deprecate_positional_args
328 def load_jupiter(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
329 """Load the planet Jupiter as a textured sphere.
330
331 Parameters
332 ----------
333 radius : float, default: 1.0
334 Sphere radius.
335
336 lat_resolution : int, default: 50
337 Set the number of points in the latitude direction.
338
339 lon_resolution : int, default: 100
340 Set the number of points in the longitude direction.
341
342 Returns
343 -------
344 pyvista.PolyData
345 Jupiter dataset.
346
347 Examples
348 --------
349 >>> import pyvista as pv
350 >>> from pyvista import examples
351 >>> mesh = examples.planets.load_jupiter()
352 >>> texture = examples.planets.download_jupiter_surface(texture=True)
353 >>> image_path = examples.planets.download_stars_sky_background(load=False)
354 >>> mesh.plot(texture=texture, background=image_path)
355
356 .. seealso::
357
358 :func:`~pyvista.examples.planets.download_jupiter_surface`
359 Download the surface of Jupiter.
360
361 :ref:`planets_example`
362 Example plot of the solar system.
363
364 """
365 return _sphere_with_texture_map(
366 radius=radius,
367 lat_resolution=lat_resolution,
368 lon_resolution=lon_resolution,
369 )
370
371
372 @_deprecate_positional_args
373 def load_saturn(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
374 """Load the planet Saturn as a textured sphere.
375
376 Parameters
377 ----------
378 radius : float, default: 1.0
379 Sphere radius.
380
381 lat_resolution : int, default: 50
382 Set the number of points in the latitude direction.
383
384 lon_resolution : int, default: 100
385 Set the number of points in the longitude direction.
386
387 Returns
388 -------
389 pyvista.PolyData
390 Saturn dataset.
391
392 Examples
393 --------
394 >>> import pyvista as pv
395 >>> from pyvista import examples
396 >>> mesh = examples.planets.load_saturn()
397 >>> texture = examples.planets.download_saturn_surface(texture=True)
398 >>> image_path = examples.planets.download_stars_sky_background(load=False)
399 >>> mesh.plot(texture=texture, background=image_path)
400
401 .. seealso::
402
403 :func:`~pyvista.examples.planets.download_saturn_surface`
404 Download the surface of Saturn.
405
406 :func:`~pyvista.examples.planets.load_saturn_rings`
407 Load Saturn's rings as a textured disc.
408
409 :func:`~pyvista.examples.planets.download_saturn_rings`
410 Download the texture of Saturn's rings.
411
412 :ref:`planets_example`
413 Example plot of the solar system.
414
415 """
416 return _sphere_with_texture_map(
417 radius=radius,
418 lat_resolution=lat_resolution,
419 lon_resolution=lon_resolution,
420 )
421
422
423 @_deprecate_positional_args
424 def load_saturn_rings(inner=0.25, outer=0.5, c_res=6): # pragma: no cover
425 """Load the planet Saturn's rings.
426
427 Arguments are passed on to :func:`pyvista.Disc`.
428
429 Parameters
430 ----------
431 inner : float, optional
432 The inner radius.
433
434 outer : float, optional
435 The outer radius.
436
437 c_res : int, optional
438 The number of points in the circumferential direction.
439
440 Returns
441 -------
442 pyvista.PolyData
443 Dataset with texture for Saturn's rings.
444
445 Examples
446 --------
447 >>> import pyvista as pv
448 >>> from pyvista import examples
449 >>> mesh = examples.planets.load_saturn_rings()
450 >>> texture = examples.planets.download_saturn_rings(texture=True)
451 >>> image_path = examples.planets.download_stars_sky_background(load=False)
452 >>> mesh.plot(texture=texture, background=image_path)
453
454 .. seealso::
455
456 :func:`~pyvista.examples.planets.download_saturn_rings`
457 Download the texture of Saturn's rings.
458
459 :func:`~pyvista.examples.planets.load_saturn`
460 Load the planet Saturn as a textured sphere.
461
462 :func:`~pyvista.examples.planets.download_saturn_surface`
463 Download the surface of Saturn.
464
465 :ref:`planets_example`
466 Example plot of the solar system.
467
468 """
469 disc = pv.Disc(inner=inner, outer=outer, c_res=c_res)
470 texture_coordinates = np.zeros((disc.points.shape[0], 2))
471 radius = np.sqrt(disc.points[:, 0] ** 2 + disc.points[:, 1] ** 2)
472 texture_coordinates[:, 0] = (radius - inner) / (outer - inner)
473 texture_coordinates[:, 1] = 0.0
474 disc.active_texture_coordinates = texture_coordinates
475 return disc
476
477
478 @_deprecate_positional_args
479 def load_uranus(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
480 """Load the planet Uranus as a textured sphere.
481
482 Parameters
483 ----------
484 radius : float, default: 1.0
485 Sphere radius.
486
487 lat_resolution : int, default: 50
488 Set the number of points in the latitude direction.
489
490 lon_resolution : int, default: 100
491 Set the number of points in the longitude direction.
492
493 Returns
494 -------
495 pyvista.PolyData
496 Uranus dataset.
497
498 Examples
499 --------
500 >>> import pyvista as pv
501 >>> from pyvista import examples
502 >>> mesh = examples.planets.load_uranus()
503 >>> texture = examples.planets.download_uranus_surface(texture=True)
504 >>> image_path = examples.planets.download_stars_sky_background(load=False)
505 >>> mesh.plot(texture=texture, background=image_path)
506
507 .. seealso::
508
509 :func:`~pyvista.examples.planets.download_uranus_surface`
510 Download the surface of Uranus.
511
512 :ref:`planets_example`
513 Example plot of the solar system.
514
515 """
516 return _sphere_with_texture_map(
517 radius=radius,
518 lat_resolution=lat_resolution,
519 lon_resolution=lon_resolution,
520 )
521
522
523 @_deprecate_positional_args
524 def load_neptune(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
525 """Load the planet Neptune as a textured sphere.
526
527 Parameters
528 ----------
529 radius : float, default: 1.0
530 Sphere radius.
531
532 lat_resolution : int, default: 50
533 Set the number of points in the latitude direction.
534
535 lon_resolution : int, default: 100
536 Set the number of points in the longitude direction.
537
538 Returns
539 -------
540 pyvista.PolyData
541 Neptune dataset.
542
543 Examples
544 --------
545 >>> import pyvista as pv
546 >>> from pyvista import examples
547 >>> mesh = examples.planets.load_neptune()
548 >>> texture = examples.planets.download_neptune_surface(texture=True)
549 >>> image_path = examples.planets.download_stars_sky_background(load=False)
550 >>> mesh.plot(texture=texture, background=image_path)
551
552 .. seealso::
553
554 :func:`~pyvista.examples.planets.download_neptune_surface`
555 Download the surface of Neptune.
556
557 :ref:`planets_example`
558 Example plot of the solar system.
559
560 """
561 return _sphere_with_texture_map(
562 radius=radius,
563 lat_resolution=lat_resolution,
564 lon_resolution=lon_resolution,
565 )
566
567
568 @_deprecate_positional_args
569 def load_pluto(radius=1.0, lat_resolution=50, lon_resolution=100): # pragma: no cover
570 """Load the dwarf planet Pluto as a textured sphere.
571
572 Parameters
573 ----------
574 radius : float, default: 1.0
575 Sphere radius.
576
577 lat_resolution : int, default: 50
578 Set the number of points in the latitude direction.
579
580 lon_resolution : int, default: 100
581 Set the number of points in the longitude direction.
582
583 Returns
584 -------
585 pyvista.PolyData
586 Pluto dataset.
587
588 Examples
589 --------
590 >>> import pyvista as pv
591 >>> from pyvista import examples
592 >>> mesh = examples.planets.load_pluto()
593 >>> texture = examples.planets.download_pluto_surface(texture=True)
594 >>> image_path = examples.planets.download_stars_sky_background(load=False)
595 >>> mesh.plot(texture=texture, background=image_path)
596
597 .. seealso::
598
599 :func:`~pyvista.examples.planets.download_pluto_surface`
600 Download the surface of Pluto.
601
602 :ref:`planets_example`
603 Example plot of the solar system.
604
605 """
606 return _sphere_with_texture_map(
607 radius=radius,
608 lat_resolution=lat_resolution,
609 lon_resolution=lon_resolution,
610 )
611
612
613 @_deprecate_positional_args
614 def download_sun_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
615 """Download the surface of the Sun.
616
617 Textures obtained from `Solar Textures
618 <https://www.solarsystemscope.com/textures/>`_.
619
620 Parameters
621 ----------
622 texture : bool, default: False
623 Set to ``True`` when loading the surface as a texture.
624
625 load : bool, default: True
626 Load the dataset. When ``False``, return the path to the file.
627
628 Returns
629 -------
630 output : pyvista.DataSet | pyvista.Texture | str
631 Texture, Dataset, or path to the file depending on the ``load`` and
632 ``texture`` parameters.
633
634 Examples
635 --------
636 >>> from pyvista import examples
637 >>> texture = examples.planets.download_sun_surface(texture=True)
638 >>> texture.plot(zoom='tight', show_axes=False)
639
640 .. seealso::
641
642 :ref:`Sun Surface Dataset <sun_surface_dataset>`
643 See this dataset in the Dataset Gallery for more info.
644
645 :func:`~pyvista.examples.planets.load_sun`
646 Load the Sun as a textured sphere.
647
648 :ref:`planets_example`
649 Example plot of the solar system.
650
651 """
652 return _download_dataset_texture(_dataset_sun_surface, load=load, texture=texture)
653
654
655 _dataset_sun_surface = _SingleFileDownloadableDatasetLoader(
656 'solar_textures/sun.jpg',
657 )
658
659
660 @_deprecate_positional_args
661 def download_moon_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
662 """Download the surface of the Earth's Moon.
663
664 Textures obtained from `Solar Textures
665 <https://www.solarsystemscope.com/textures/>`_.
666
667 Parameters
668 ----------
669 texture : bool, default: False
670 Set to ``True`` when loading the surface as a texture.
671
672 load : bool, default: True
673 Load the dataset. When ``False``, return the path to the file.
674
675 Returns
676 -------
677 output : pyvista.DataSet | pyvista.Texture | str
678 Texture, Dataset, or path to the file depending on the ``load`` and
679 ``texture`` parameters.
680
681 Examples
682 --------
683 >>> from pyvista import examples
684 >>> texture = examples.planets.download_moon_surface(texture=True)
685 >>> texture.plot(zoom='tight', show_axes=False)
686
687 .. seealso::
688
689 :ref:`Moon Surface Dataset <moon_surface_dataset>`
690 See this dataset in the Dataset Gallery for more info.
691
692 :func:`~pyvista.examples.planets.load_moon`
693 Load the Moon as a textured sphere.
694
695 :ref:`planets_example`
696 Example plot of the solar system.
697
698 """
699 return _download_dataset_texture(_dataset_moon_surface, load=load, texture=texture)
700
701
702 _dataset_moon_surface = _SingleFileDownloadableDatasetLoader(
703 'solar_textures/moon.jpg',
704 )
705
706
707 @_deprecate_positional_args
708 def download_mercury_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
709 """Download the surface of planet Mercury.
710
711 Textures obtained from `Solar Textures
712 <https://www.solarsystemscope.com/textures/>`_.
713
714 Parameters
715 ----------
716 texture : bool, default: False
717 Set to ``True`` when loading the surface as a texture.
718
719 load : bool, default: True
720 Load the dataset. When ``False``, return the path to the file.
721
722 Returns
723 -------
724 output : pyvista.DataSet | pyvista.Texture | str
725 Texture, Dataset, or path to the file depending on the ``load`` and
726 ``texture`` parameters.
727
728 Examples
729 --------
730 >>> from pyvista import examples
731 >>> texture = examples.planets.download_mercury_surface(texture=True)
732 >>> texture.plot(zoom='tight', show_axes=False)
733
734 .. seealso::
735
736 :ref:`Mercury Surface Dataset <mercury_surface_dataset>`
737 See this dataset in the Dataset Gallery for more info.
738
739 :func:`~pyvista.examples.planets.load_mercury`
740 Load Mercury as a textured sphere.
741
742 :ref:`planets_example`
743 Example plot of the solar system.
744
745 """
746 return _download_dataset_texture(_dataset_mercury_surface, load=load, texture=texture)
747
748
749 _dataset_mercury_surface = _SingleFileDownloadableDatasetLoader(
750 'solar_textures/mercury.jpg',
751 )
752
753
754 @_deprecate_positional_args
755 def download_venus_surface(
756 atmosphere=True, # noqa: FBT002
757 texture=False, # noqa: FBT002
758 load=True, # noqa: FBT002
759 ): # pragma: no cover
760 """Download the surface or atmosphere of Planet Venus.
761
762 Textures obtained from `Solar Textures
763 <https://www.solarsystemscope.com/textures/>`_.
764
765 Parameters
766 ----------
767 atmosphere : bool, optional
768 Load the atmosphere texture when ``True``.
769
770 texture : bool, default: False
771 Set to ``True`` when loading the surface as a texture.
772
773 load : bool, default: True
774 Load the dataset. When ``False``, return the path to the file.
775
776 Returns
777 -------
778 output : pyvista.DataSet | pyvista.Texture | str
779 Texture, Dataset, or path to the file depending on the ``load`` and
780 ``texture`` parameters.
781
782 Examples
783 --------
784 >>> from pyvista import examples
785 >>> texture = examples.planets.download_venus_surface(texture=True)
786 >>> texture.plot(zoom='tight', show_axes=False)
787
788 .. seealso::
789
790 :ref:`Venus Surface Dataset <venus_surface_dataset>`
791 See this dataset in the Dataset Gallery for more info.
792
793 :func:`~pyvista.examples.planets.load_venus`
794 Load Venus as a textured sphere.
795
796 :ref:`planets_example`
797 Example plot of the solar system.
798
799 """
800 if atmosphere:
801 return _download_dataset_texture(_dataset_venus_surface, load=load, texture=texture)
802 return _download_dataset_texture(
803 __dataset_venus_surface_no_atmosphere, load=load, texture=texture
804 )
805
806
807 _dataset_venus_surface = _SingleFileDownloadableDatasetLoader(
808 'solar_textures/venus_atmosphere.jpg',
809 )
810 __dataset_venus_surface_no_atmosphere = _SingleFileDownloadableDatasetLoader(
811 'solar_textures/venus_surface.jpg',
812 )
813
814
815 @_deprecate_positional_args
816 def download_mars_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
817 """Download the surface of the planet Mars.
818
819 Textures obtained from `Solar Textures
820 <https://www.solarsystemscope.com/textures/>`_.
821
822 Parameters
823 ----------
824 texture : bool, default: False
825 Set to ``True`` when loading the surface as a texture.
826
827 load : bool, default: True
828 Load the dataset. When ``False``, return the path to the file.
829
830 Returns
831 -------
832 output : pyvista.DataSet | pyvista.Texture | str
833 Texture, Dataset, or path to the file depending on the ``load`` and
834 ``texture`` parameters.
835
836 Examples
837 --------
838 >>> from pyvista import examples
839 >>> texture = examples.planets.download_mars_surface(texture=True)
840 >>> texture.plot(zoom='tight', show_axes=False)
841
842 .. seealso::
843
844 :ref:`Mars Surface Dataset <mars_surface_dataset>`
845 See this dataset in the Dataset Gallery for more info.
846
847 :func:`~pyvista.examples.planets.load_mars`
848 Load Mars as a textured sphere.
849
850 :ref:`planets_example`
851 Example plot of the solar system.
852
853 """
854 return _download_dataset_texture(_dataset_mars_surface, load=load, texture=texture)
855
856
857 _dataset_mars_surface = _SingleFileDownloadableDatasetLoader(
858 'solar_textures/mars.jpg',
859 )
860
861
862 @_deprecate_positional_args
863 def download_jupiter_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
864 """Download the surface of the planet Jupiter.
865
866 Textures obtained from `Solar Textures
867 <https://www.solarsystemscope.com/textures/>`_.
868
869 Parameters
870 ----------
871 texture : bool, default: False
872 Set to ``True`` when loading the surface as a texture.
873
874 load : bool, default: True
875 Load the dataset. When ``False``, return the path to the file.
876
877 Returns
878 -------
879 output : pyvista.DataSet | pyvista.Texture | str
880 Texture, Dataset, or path to the file depending on the ``load`` and
881 ``texture`` parameters.
882
883 Examples
884 --------
885 >>> from pyvista import examples
886 >>> texture = examples.planets.download_jupiter_surface(texture=True)
887 >>> texture.plot(zoom='tight', show_axes=False)
888
889 .. seealso::
890
891 :ref:`Jupiter Surface Dataset <jupiter_surface_dataset>`
892 See this dataset in the Dataset Gallery for more info.
893
894 :func:`~pyvista.examples.planets.load_jupiter`
895 Load Jupiter as a textured sphere.
896
897 :ref:`planets_example`
898 Example plot of the solar system.
899
900 """
901 return _download_dataset_texture(_dataset_jupiter_surface, load=load, texture=texture)
902
903
904 _dataset_jupiter_surface = _SingleFileDownloadableDatasetLoader(
905 'solar_textures/jupiter.jpg',
906 )
907
908
909 @_deprecate_positional_args
910 def download_saturn_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
911 """Download the surface of the planet Saturn.
912
913 Textures obtained from `Solar Textures
914 <https://www.solarsystemscope.com/textures/>`_.
915
916 Parameters
917 ----------
918 texture : bool, default: False
919 Set to ``True`` when loading the surface as a texture.
920
921 load : bool, default: True
922 Load the dataset. When ``False``, return the path to the file.
923
924 Returns
925 -------
926 output : pyvista.DataSet | pyvista.Texture | str
927 Texture, Dataset, or path to the file depending on the ``load`` and
928 ``texture`` parameters.
929
930 Examples
931 --------
932 >>> from pyvista import examples
933 >>> texture = examples.planets.download_saturn_surface(texture=True)
934 >>> texture.plot(zoom='tight', show_axes=False)
935
936 .. seealso::
937
938 :ref:`Saturn Surface Dataset <saturn_surface_dataset>`
939 See this dataset in the Dataset Gallery for more info.
940
941 :func:`~pyvista.examples.planets.load_saturn`
942 Load the planet Saturn as a textured sphere.
943
944 :func:`~pyvista.examples.planets.load_saturn_rings`
945 Load Saturn's rings as a textured disc.
946
947 :func:`~pyvista.examples.planets.download_saturn_rings`
948 Download the texture of Saturn's rings.
949
950 :ref:`planets_example`
951 Example plot of the solar system.
952
953 """
954 return _download_dataset_texture(_dataset_saturn_surface, load=load, texture=texture)
955
956
957 _dataset_saturn_surface = _SingleFileDownloadableDatasetLoader(
958 'solar_textures/saturn.jpg',
959 )
960
961
962 @_deprecate_positional_args
963 def download_saturn_rings(texture=False, load=True): # pragma: no cover # noqa: FBT002
964 """Download the texture of Saturn's rings.
965
966 Textures obtained from `Solar Textures
967 <https://www.solarsystemscope.com/textures/>`_.
968
969 Parameters
970 ----------
971 texture : bool, default: False
972 Set to ``True`` when loading the surface as a texture.
973
974 load : bool, default: True
975 Load the dataset. When ``False``, return the path to the file.
976
977 Returns
978 -------
979 output : pyvista.ImageData | pyvista.Texture | str
980 Dataset, texture, or filename of the Saturn's rings.
981
982 Examples
983 --------
984 >>> from pyvista import examples
985 >>> texture = examples.planets.download_saturn_rings(texture=True)
986 >>> texture.plot(cpos='xy')
987
988 .. seealso::
989
990 :ref:`Saturn Rings Dataset <saturn_rings_dataset>`
991 See this dataset in the Dataset Gallery for more info.
992
993 :func:`~pyvista.examples.planets.load_saturn_rings`
994 Load Saturn's rings as a textured disc.
995
996 :func:`~pyvista.examples.planets.load_saturn`
997 Load the planet Saturn as a textured sphere.
998
999 :func:`~pyvista.examples.planets.download_saturn_surface`
1000 Download the surface of Saturn.
1001
1002 :ref:`planets_example`
1003 Example plot of the solar system.
1004
1005 """
1006 return _download_dataset_texture(_dataset_saturn_rings, load=load, texture=texture)
1007
1008
1009 _dataset_saturn_rings = _SingleFileDownloadableDatasetLoader(
1010 'solar_textures/saturn_ring_alpha.png',
1011 )
1012
1013
1014 @_deprecate_positional_args
1015 def download_uranus_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
1016 """Download and the texture of the surface of planet Uranus.
1017
1018 Textures obtained from `Solar Textures
1019 <https://www.solarsystemscope.com/textures/>`_.
1020
1021 Parameters
1022 ----------
1023 texture : bool, default: False
1024 Set to ``True`` when loading the surface as a texture.
1025
1026 load : bool, default: True
1027 Load the dataset. When ``False``, return the path to the file.
1028
1029 Returns
1030 -------
1031 output : pyvista.DataSet | pyvista.Texture | str
1032 Texture, Dataset, or path to the file depending on the ``load`` and
1033 ``texture`` parameters.
1034
1035 Examples
1036 --------
1037 >>> from pyvista import examples
1038 >>> texture = examples.planets.download_uranus_surface(texture=True)
1039 >>> texture.plot(zoom='tight', show_axes=False)
1040
1041 .. seealso::
1042
1043 :ref:`Uranus Surface Dataset <uranus_surface_dataset>`
1044 See this dataset in the Dataset Gallery for more info.
1045
1046 :func:`~pyvista.examples.planets.load_uranus`
1047 Load Uranus as a textured sphere.
1048
1049 :ref:`planets_example`
1050 Example plot of the solar system.
1051
1052 """
1053 return _download_dataset_texture(_dataset_uranus_surface, load=load, texture=texture)
1054
1055
1056 _dataset_uranus_surface = _SingleFileDownloadableDatasetLoader(
1057 'solar_textures/uranus.jpg',
1058 )
1059
1060
1061 @_deprecate_positional_args
1062 def download_neptune_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
1063 """Download the texture of the surface of planet Neptune.
1064
1065 Textures obtained from `Solar Textures
1066 <https://www.solarsystemscope.com/textures/>`_.
1067
1068 Parameters
1069 ----------
1070 texture : bool, default: False
1071 Set to ``True`` when loading the surface as a texture.
1072
1073 load : bool, default: True
1074 Load the dataset. When ``False``, return the path to the file.
1075
1076 Returns
1077 -------
1078 output : pyvista.DataSet | pyvista.Texture | str
1079 Texture, Dataset, or path to the file depending on the ``load`` and
1080 ``texture`` parameters.
1081
1082 Examples
1083 --------
1084 >>> from pyvista import examples
1085 >>> texture = examples.planets.download_neptune_surface(texture=True)
1086 >>> texture.plot(zoom='tight', show_axes=False)
1087
1088 .. seealso::
1089
1090 :ref:`Neptune Surface Dataset <neptune_surface_dataset>`
1091 See this dataset in the Dataset Gallery for more info.
1092
1093 :func:`~pyvista.examples.planets.load_neptune`
1094 Load Neptune as a textured sphere.
1095
1096 :ref:`planets_example`
1097 Example plot of the solar system.
1098
1099 """
1100 return _download_dataset_texture(_dataset_neptune_surface, load=load, texture=texture)
1101
1102
1103 _dataset_neptune_surface = _SingleFileDownloadableDatasetLoader(
1104 'solar_textures/neptune.jpg',
1105 )
1106
1107
1108 @_deprecate_positional_args
1109 def download_pluto_surface(texture=False, load=True): # pragma: no cover # noqa: FBT002
1110 """Download the texture of the surface of the dwarf planet Pluto.
1111
1112 Textures obtained from `Solar Textures
1113 <https://www.solarsystemscope.com/textures/>`_.
1114
1115 Parameters
1116 ----------
1117 texture : bool, default: False
1118 Set to ``True`` when loading the surface as a texture.
1119
1120 load : bool, default: True
1121 Load the dataset. When ``False``, return the path to the file.
1122
1123 Returns
1124 -------
1125 output : pyvista.DataSet | pyvista.Texture | str
1126 Texture, Dataset, or path to the file depending on the ``load`` and
1127 ``texture`` parameters.
1128
1129 Examples
1130 --------
1131 >>> from pyvista import examples
1132 >>> texture = examples.planets.download_pluto_surface(texture=True)
1133 >>> texture.plot(zoom='tight', show_axes=False)
1134
1135 .. seealso::
1136
1137 :ref:`Pluto Surface Dataset <pluto_surface_dataset>`
1138 See this dataset in the Dataset Gallery for more info.
1139
1140 :func:`~pyvista.examples.planets.load_pluto`
1141 Load Pluto as a textured sphere.
1142
1143 :ref:`planets_example`
1144 Example plot of the solar system.
1145
1146 """
1147 return _download_dataset_texture(_dataset_pluto_surface, load=load, texture=texture)
1148
1149
1150 _dataset_pluto_surface = _SingleFileDownloadableDatasetLoader(
1151 'solar_textures/pluto.jpg',
1152 )
1153
1154
1155 @_deprecate_positional_args
1156 def download_stars_sky_background(texture=False, load=True): # pragma: no cover # noqa: FBT002
1157 """Download the night sky stars texture.
1158
1159 Textures obtained from `tamaskis/planet3D-MATLAB
1160 <https://github.com/tamaskis/planet3D-MATLAB>`_.
1161
1162 Parameters
1163 ----------
1164 texture : bool, default: False
1165 Set to ``True`` when loading the surface as a texture.
1166
1167 load : bool, default: True
1168 Load the dataset. When ``False``, return the path to the file.
1169
1170 Returns
1171 -------
1172 output : pyvista.DataSet | pyvista.Texture | str
1173 Texture, Dataset, or path to the file depending on the ``load`` and
1174 ``texture`` parameters.
1175
1176 Examples
1177 --------
1178 Load the night sky image as a background image.
1179
1180 >>> from pyvista import examples
1181 >>> import pyvista as pv
1182 >>> pl = pv.Plotter()
1183 >>> image_path = examples.planets.download_stars_sky_background(load=False)
1184 >>> pl.add_background_image(image_path)
1185 >>> pl.show()
1186
1187
1188 .. seealso::
1189
1190 :ref:`Stars Sky Background Dataset <stars_sky_background_dataset>`
1191 See this dataset in the Dataset Gallery for more info.
1192
1193 :func:`~pyvista.examples.planets.load_mars`
1194 Load Mars as a textured sphere.
1195
1196 :ref:`Milkyway Sky Background Dataset <milkyway_sky_background_dataset>`
1197 Sky texture of the Milky Way galaxy.
1198
1199 :ref:`planets_example`
1200 Example plot of the solar system.
1201
1202 """
1203 return _download_dataset_texture(_dataset_stars_sky_background, load=load, texture=texture)
1204
1205
1206 _dataset_stars_sky_background = _SingleFileDownloadableDatasetLoader(
1207 'planet3d-matlab/stars.jpg',
1208 )
1209
1210
1211 @_deprecate_positional_args
1212 def download_milkyway_sky_background(texture=False, load=True): # pragma: no cover # noqa: FBT002
1213 """Download the sky texture of the Milky Way galaxy.
1214
1215 Textures obtained from `tamaskis/planet3D-MATLAB
1216 <https://github.com/tamaskis/planet3D-MATLAB>`_.
1217
1218 Parameters
1219 ----------
1220 texture : bool, default: False
1221 Set to ``True`` when loading the surface as a texture.
1222
1223 load : bool, default: True
1224 Load the dataset. When ``False``, return the path to the file.
1225
1226 Returns
1227 -------
1228 output : pyvista.DataSet | pyvista.Texture | str
1229 Texture, Dataset, or path to the file depending on the ``load`` and
1230 ``texture`` parameters.
1231
1232 Examples
1233 --------
1234 Load the Milky Way sky image as a background image.
1235
1236 >>> from pyvista import examples
1237 >>> import pyvista as pv
1238 >>> pl = pv.Plotter()
1239 >>> image_path = examples.planets.download_milkyway_sky_background(load=False)
1240 >>> pl.add_background_image(image_path)
1241 >>> pl.show()
1242
1243 .. seealso::
1244
1245 :ref:`Milkyway Sky Background Dataset <milkyway_sky_background_dataset>`
1246 See this dataset in the Dataset Gallery for more info.
1247
1248 :ref:`Stars Sky Background Dataset <stars_sky_background_dataset>`
1249 Night sky stars texture.
1250
1251 :ref:`planets_example`
1252 Example plot of the solar system.
1253
1254 """
1255 return _download_dataset_texture(_dataset_milkyway_sky_background, load=load, texture=texture)
1256
1257
1258 _dataset_milkyway_sky_background = _SingleFileDownloadableDatasetLoader(
1259 'planet3d-matlab/milkyway.jpg',
1260 )