render_povray/render_properties.py

   1 # SPDX-FileCopyrightText: 2021-2022 Blender Foundation
   2 #
   3 # SPDX-License-Identifier: GPL-2.0-or-later
   4
   5 """Declare rendering properties controllable in UI"""
   6
   7 import bpy
   8 from bpy.utils import register_class, unregister_class
   9 from bpy.types import PropertyGroup, Scene
  10 from bpy.props import (
  11     BoolProperty,
  12     IntProperty,
  13     FloatProperty,
  14     FloatVectorProperty,
  15     StringProperty,
  16     EnumProperty,
  17     PointerProperty,
  18 )
  19
  20
  21 # ---------------------------------------------------------------- #
  22 # Scene POV properties.
  23 # ---------------------------------------------------------------- #
  24 class RenderPovSettingsScene(PropertyGroup):
  25
  26     """Declare scene level properties controllable in UI and translated to POV"""
  27
  28     # Linux SDL-window enable
  29     sdl_window_enable: BoolProperty(
  30         name="Enable SDL window", description="Enable the SDL window in Linux OS", default=True
  31     )
  32     # File Options
  33     text_block: StringProperty(
  34         name="Text Scene Name",
  35         description="Name of POV scene to use. "
  36         "Set when clicking Run to render current text only",
  37         maxlen=1024,
  38     )
  39     tempfiles_enable: BoolProperty(
  40         name="Enable Tempfiles",
  41         description="Enable the OS-Tempfiles. Otherwise set the path where to save the files",
  42         default=True,
  43     )
  44     pov_editor: BoolProperty(
  45         name="POV editor",
  46         description="Don't Close POV editor after rendering (Overridden by /EXIT command)",
  47         default=False,
  48     )
  49     deletefiles_enable: BoolProperty(
  50         name="Delete files",
  51         description="Delete files after rendering. Doesn't work with the image",
  52         default=True,
  53     )
  54     scene_name: StringProperty(
  55         name="Scene Name",
  56         description="Name of POV scene to create. Empty name will use "
  57         "the name of the blend file",
  58         maxlen=1024,
  59     )
  60     scene_path: StringProperty(
  61         name="Export scene path",
  62         # Bug in POV-Ray RC3
  63         # description="Path to directory where the exported scene "
  64         # "(POV and INI) is created",
  65         description="Path to directory where the files are created",
  66         maxlen=1024,
  67         subtype="DIR_PATH",
  68     )
  69     renderimage_path: StringProperty(
  70         name="Rendered image path",
  71         description="Full path to directory where the rendered image is saved",
  72         maxlen=1024,
  73         subtype="DIR_PATH",
  74     )
  75     list_lf_enable: BoolProperty(
  76         name="LF in lists",
  77         description="Enable line breaks in lists (vectors and indices). "
  78         "Disabled: lists are exported in one line",
  79         default=False,
  80     )
  81
  82     # Not a real pov option, just to know if we should write
  83     radio_enable: BoolProperty(
  84         name="Enable Radiosity", description="Enable POV radiosity calculation", default=True
  85     )
  86
  87     radio_display_advanced: BoolProperty(
  88         name="Advanced Options", description="Show advanced options", default=False
  89     )
  90
  91     media_enable: BoolProperty(
  92         name="Enable Media", description="Enable POV atmospheric media", default=False
  93     )
  94
  95     media_samples: IntProperty(
  96         name="Samples",
  97         description="Number of samples taken from camera to first object "
  98         "encountered along ray path for media calculation",
  99         min=1,
 100         max=100,
 101         default=35,
 102     )
 103
 104     media_scattering_type: EnumProperty(
 105         name="Scattering Type",
 106         description="Scattering model",
 107         items=(
 108             (
 109                 "1",
 110                 "1 Isotropic",
 111                 "The simplest form of scattering because it is independent of direction.",
 112             ),
 113             (
 114                 "2",
 115                 "2 Mie haze ",
 116                 "For relatively small particles such as "
 117                 "minuscule water droplets of fog, cloud "
 118                 "particles, and particles responsible "
 119                 "for the polluted sky. In this model the"
 120                 " scattering is extremely directional in"
 121                 " the forward direction i.e. the amount "
 122                 "of scattered light is largest when the "
 123                 "incident light is anti-parallel to the "
 124                 "viewing direction (the light goes "
 125                 "directly to the viewer). It is smallest"
 126                 " when the incident light is parallel to"
 127                 " the viewing direction. ",
 128             ),
 129             ("3", "3 Mie murky", "Like haze but much more directional"),
 130             (
 131                 "4",
 132                 "4 Rayleigh",
 133                 "For extremely small particles such as "
 134                 "molecules of the air. The amount of "
 135                 "scattered light depends on the incident"
 136                 " light angle. It is largest when the "
 137                 "incident light is parallel or "
 138                 "anti-parallel to the viewing direction "
 139                 "and smallest when the incident light is "
 140                 "perpendicular to viewing direction.",
 141             ),
 142             (
 143                 "5",
 144                 "5 Henyey-Greenstein",
 145                 "The default eccentricity value "
 146                 "of zero defines isotropic "
 147                 "scattering while positive "
 148                 "values lead to scattering in "
 149                 "the direction of the light and "
 150                 "negative values lead to "
 151                 "scattering in the opposite "
 152                 "direction of the light. Larger "
 153                 "values of e (or smaller values "
 154                 "in the negative case) increase "
 155                 "the directional property of the"
 156                 " scattering.",
 157             ),
 158         ),
 159         default="1",
 160     )
 161
 162     media_diffusion_scale: FloatProperty(
 163         name="Scale",
 164         description="Scale factor of Media Diffusion Color",
 165         precision=6,
 166         step=0.00000001,
 167         min=0.000000001,
 168         max=1.0,
 169         default=1.0,
 170     )
 171
 172     media_diffusion_color: FloatVectorProperty(
 173         name="Media Diffusion Color",
 174         description="The atmospheric media color",
 175         precision=4,
 176         step=0.01,
 177         min=0,
 178         soft_max=1,
 179         default=(0.001, 0.001, 0.001),
 180         options={"ANIMATABLE"},
 181         subtype="COLOR",
 182     )
 183
 184     media_absorption_scale: FloatProperty(
 185         name="Scale",
 186         description="Scale factor of Media Absorption Color. "
 187         "use 1/depth of media volume in meters",
 188         precision=6,
 189         step=0.000001,
 190         min=0.000000001,
 191         max=1.0,
 192         default=0.00002,
 193     )
 194
 195     media_absorption_color: FloatVectorProperty(
 196         name="Media Absorption Color",
 197         description="The atmospheric media absorption color",
 198         precision=4,
 199         step=0.01,
 200         min=0,
 201         soft_max=1,
 202         default=(0.0, 0.0, 0.0),
 203         options={"ANIMATABLE"},
 204         subtype="COLOR",
 205     )
 206
 207     media_eccentricity: FloatProperty(
 208         name="Media Eccenticity Factor",
 209         description="Positive values lead"
 210         " to scattering in the direction of the light and negative "
 211         "values lead to scattering in the opposite direction of the "
 212         "light. Larger values of e (or smaller values in the negative"
 213         " case) increase the directional property of the scattering",
 214         precision=2,
 215         step=0.01,
 216         min=-1.0,
 217         max=1.0,
 218         default=0.0,
 219         options={"ANIMATABLE"},
 220     )
 221
 222     baking_enable: BoolProperty(
 223         name="Enable Baking", description="Enable POV texture baking", default=False
 224     )
 225
 226     indentation_character: EnumProperty(
 227         name="Indentation",
 228         description="Select the indentation type",
 229         items=(
 230             ("NONE", "None", "No indentation"),
 231             ("TAB", "Tabs", "Indentation with tabs"),
 232             ("SPACE", "Spaces", "Indentation with spaces"),
 233         ),
 234         default="SPACE",
 235     )
 236
 237     indentation_spaces: IntProperty(
 238         name="Quantity of spaces",
 239         description="The number of spaces for indentation",
 240         min=1,
 241         max=10,
 242         default=4,
 243     )
 244
 245     comments_enable: BoolProperty(
 246         name="Enable Comments", description="Add comments to pov file", default=True
 247     )
 248
 249     # Real pov options
 250     command_line_switches: StringProperty(
 251         name="Command Line Switches",
 252         description="Command line switches consist of a + (plus) or - "
 253         "(minus) sign, followed by one or more alphabetic "
 254         "characters and possibly a numeric value",
 255         maxlen=500,
 256     )
 257
 258     antialias_enable: BoolProperty(
 259         name="Anti-Alias", description="Enable Anti-Aliasing", default=True
 260     )
 261
 262     antialias_method: EnumProperty(
 263         name="Method",
 264         description="AA-sampling method. Type 1 is an adaptive, "
 265         "non-recursive, super-sampling (as in the plain old render "
 266         "bigger and scale down trick. Type 2 is a slightly "
 267         "more efficient adaptive and recursive super-sampling. "
 268         "Type 3 is a stochastic halton based super-sampling method so "
 269         "rather artifact free and sampling rays so depth of field can "
 270         "use them at no additional cost, as do area lights and "
 271         "subsurface scattering materials, making it the best "
 272         "quality / time trade-off in complex scenes",
 273         items=(
 274             ("0", "non-recursive AA", "Type 1 Sampling in POV"),
 275             ("1", "recursive AA", "Type 2 Sampling in POV"),
 276             ("2", "stochastic AA", "Type 3 Sampling in POV"),
 277         ),
 278         default="1",
 279     )
 280
 281     antialias_confidence: FloatProperty(
 282         name="Antialias Confidence",
 283         description="how surely the computed color "
 284         "of a given pixel is indeed"
 285         "within the threshold error margin",
 286         min=0.0001,
 287         max=1.0000,
 288         default=0.9900,
 289         precision=4,
 290     )
 291
 292     antialias_depth: IntProperty(
 293         name="Antialias Depth", description="Depth of pixel for sampling", min=1, max=9, default=2
 294     )
 295
 296     antialias_threshold: FloatProperty(
 297         name="Antialias Threshold",
 298         description="Tolerance for sub-pixels",
 299         min=0.0,
 300         max=1.0,
 301         soft_min=0.05,
 302         soft_max=0.5,
 303         default=0.03,
 304     )
 305
 306     jitter_enable: BoolProperty(
 307         name="Jitter",
 308         description="Enable Jittering. Adds noise into the sampling "
 309         "process (it should be avoided to use jitter in "
 310         "animation)",
 311         default=False,
 312     )
 313
 314     jitter_amount: FloatProperty(
 315         name="Jitter Amount",
 316         description="Amount of jittering",
 317         min=0.0,
 318         max=1.0,
 319         soft_min=0.01,
 320         soft_max=1.0,
 321         default=1.0,
 322     )
 323
 324     antialias_gamma: FloatProperty(
 325         name="Antialias Gamma",
 326         description="POV-Ray compares gamma-adjusted values for super "
 327         "sampling. Antialias Gamma sets the Gamma before "
 328         "comparison",
 329         min=0.0,
 330         max=5.0,
 331         soft_min=0.01,
 332         soft_max=2.5,
 333         default=2.5,
 334     )
 335
 336     alpha_filter: FloatProperty(
 337         name="Alpha",
 338         description="User defined color associated background alpha",
 339         min=0.0,
 340         max=1.0,
 341         soft_min=0.01,
 342         soft_max=1.0,
 343         default=0.75,
 344     )
 345
 346     alpha_mode: EnumProperty(
 347         name="Alpha",
 348         description="Representation of alpha information in the RGBA pixels",
 349         items=(
 350             ("SKY", "Sky", "Transparent pixels are filled with sky color"),
 351             ("STRAIGHT", "Straight", "Transparent pixels are not premultiplied"),
 352             (
 353                 "TRANSPARENT",
 354                 "Transparent",
 355                 "World background has user defined  premultiplied alpha",
 356             ),
 357         ),
 358         default="SKY",
 359     )
 360
 361     use_shadows: BoolProperty(
 362         name="Shadows", description="Calculate shadows while rendering", default=True
 363     )
 364
 365     max_trace_level: IntProperty(
 366         name="Max Trace Level",
 367         description="Number of reflections/refractions allowed on ray " "path",
 368         min=1,
 369         max=256,
 370         default=5,
 371     )
 372
 373     adc_bailout_enable: BoolProperty(name="Enable", description="", default=False)
 374
 375     adc_bailout: FloatProperty(
 376         name="ADC Bailout",
 377         description="Adaptive Depth Control (ADC) to stop computing additional"
 378         "reflected or refracted rays when their contribution is insignificant."
 379         "The default value is 1/255, or approximately 0.0039, since a change "
 380         "smaller than that could not be visible in a 24 bit image. Generally "
 381         "this value is fine and should be left alone."
 382         "Setting adc_bailout to 0 will disable ADC, relying completely on "
 383         "max_trace_level to set an upper limit on the number of rays spawned. ",
 384         min=0.0,
 385         max=1000.0,
 386         default=0.00392156862745,
 387         precision=3,
 388     )
 389
 390     ambient_light_enable: BoolProperty(name="Enable", description="", default=False)
 391
 392     ambient_light: FloatVectorProperty(
 393         name="Ambient Light",
 394         description="Ambient light is used to simulate the effect of inter-diffuse reflection",
 395         precision=4,
 396         step=0.01,
 397         min=0,
 398         soft_max=1,
 399         default=(1, 1, 1),
 400         options={"ANIMATABLE"},
 401         subtype="COLOR",
 402     )
 403     global_settings_advanced: BoolProperty(name="Advanced", description="", default=False)
 404
 405     irid_wavelength_enable: BoolProperty(name="Enable", description="", default=False)
 406
 407     irid_wavelength: FloatVectorProperty(
 408         name="Irid Wavelength",
 409         description=(
 410             "Iridescence calculations depend upon the dominant "
 411             "wavelengths of the primary colors of red, green and blue light"
 412         ),
 413         precision=4,
 414         step=0.01,
 415         min=0,
 416         soft_max=1,
 417         default=(0.25, 0.18, 0.14),
 418         options={"ANIMATABLE"},
 419         subtype="COLOR",
 420     )
 421
 422     number_of_waves_enable: BoolProperty(name="Enable", description="", default=False)
 423
 424     number_of_waves: IntProperty(
 425         name="Number Waves",
 426         description=(
 427             "The waves and ripples patterns are generated by summing a series of waves, "
 428             "each with a slightly different center and size"
 429         ),
 430         min=1,
 431         max=10,
 432         default=1000,
 433     )
 434
 435     noise_generator_enable: BoolProperty(name="Enable", description="", default=False)
 436
 437     noise_generator: IntProperty(
 438         name="Noise Generator",
 439         description="There are three noise generators implemented",
 440         min=1,
 441         max=3,
 442         default=2,
 443     )
 444
 445     # -------- PHOTONS -------- #
 446     photon_enable: BoolProperty(name="Photons", description="Enable global photons", default=False)
 447
 448     photon_enable_count: BoolProperty(
 449         name="Spacing / Count", description="Enable count photons", default=False
 450     )
 451
 452     photon_count: IntProperty(
 453         name="Count", description="Photons count", min=1, max=100000000, default=20000
 454     )
 455
 456     photon_spacing: FloatProperty(
 457         name="Spacing",
 458         description="Average distance between photons on surfaces. half "
 459         "this get four times as many surface photons",
 460         min=0.001,
 461         max=1.000,
 462         soft_min=0.001,
 463         soft_max=1.000,
 464         precision=3,
 465         default=0.005,
 466     )
 467
 468     photon_max_trace_level: IntProperty(
 469         name="Max Trace Level",
 470         description="Number of reflections/refractions allowed on ray " "path",
 471         min=1,
 472         max=256,
 473         default=5,
 474     )
 475
 476     photon_adc_bailout: FloatProperty(
 477         name="ADC Bailout",
 478         description="The adc_bailout for photons. Use adc_bailout = "
 479         "0.01 / brightest_ambient_object for good results",
 480         min=0.0,
 481         max=1000.0,
 482         soft_min=0.0,
 483         soft_max=1.0,
 484         precision=3,
 485         default=0.1,
 486     )
 487
 488     photon_gather_min: IntProperty(
 489         name="Gather Min",
 490         description="Minimum number of photons gathered" "for each point",
 491         min=1,
 492         max=256,
 493         default=20,
 494     )
 495
 496     photon_gather_max: IntProperty(
 497         name="Gather Max",
 498         description="Maximum number of photons gathered for each point",
 499         min=1,
 500         max=256,
 501         default=100,
 502     )
 503
 504     photon_map_file_save_load: EnumProperty(
 505         name="Operation",
 506         description="Load or Save photon map file",
 507         items=(("NONE", "None", ""), ("save", "Save", ""), ("load", "Load", "")),
 508         default="NONE",
 509     )
 510
 511     photon_map_filename: StringProperty(name="Filename", description="", maxlen=1024)
 512
 513     photon_map_dir: StringProperty(
 514         name="Directory", description="", maxlen=1024, subtype="DIR_PATH"
 515     )
 516
 517     photon_map_file: StringProperty(name="File", description="", maxlen=1024, subtype="FILE_PATH")
 518
 519     # -------- RADIOSITY -------- #
 520     radio_adc_bailout: FloatProperty(
 521         name="ADC Bailout",
 522         description="The adc_bailout for radiosity rays. Use "
 523         "adc_bailout = 0.01 / brightest_ambient_object for good results",
 524         min=0.0,
 525         max=1000.0,
 526         soft_min=0.0,
 527         soft_max=1.0,
 528         default=0.0039,
 529         precision=4,
 530     )
 531
 532     radio_always_sample: BoolProperty(
 533         name="Always Sample",
 534         description="Only use the data from the pretrace step and not gather "
 535         "any new samples during the final radiosity pass",
 536         default=False,
 537     )
 538
 539     radio_brightness: FloatProperty(
 540         name="Brightness",
 541         description="Amount objects are brightened before being returned "
 542         "upwards to the rest of the system",
 543         min=0.0,
 544         max=1000.0,
 545         soft_min=0.0,
 546         soft_max=10.0,
 547         default=1.0,
 548     )
 549
 550     radio_count: IntProperty(
 551         name="Ray Count",
 552         description="Number of rays for each new radiosity value to be calculated "
 553         "(halton sequence over 1600)",
 554         min=1,
 555         max=10000,
 556         soft_max=1600,
 557         default=35,
 558     )
 559
 560     radio_error_bound: FloatProperty(
 561         name="Error Bound",
 562         description="One of the two main speed/quality tuning values, "
 563         "lower values are more accurate",
 564         min=0.0,
 565         max=1000.0,
 566         soft_min=0.1,
 567         soft_max=10.0,
 568         default=10.0,
 569     )
 570
 571     radio_gray_threshold: FloatProperty(
 572         name="Gray Threshold",
 573         description="One of the two main speed/quality tuning values, "
 574         "lower values are more accurate",
 575         min=0.0,
 576         max=1.0,
 577         soft_min=0,
 578         soft_max=1,
 579         default=0.0,
 580     )
 581
 582     radio_low_error_factor: FloatProperty(
 583         name="Low Error Factor",
 584         description="Just enough samples is slightly blotchy. Low error changes error "
 585         "tolerance for less critical last refining pass",
 586         min=0.000001,
 587         max=1.0,
 588         soft_min=0.000001,
 589         soft_max=1.0,
 590         default=0.5,
 591     )
 592
 593     radio_media: BoolProperty(
 594         name="Media", description="Radiosity estimation can be affected by media", default=True
 595     )
 596
 597     radio_subsurface: BoolProperty(
 598         name="Subsurface",
 599         description="Radiosity estimation can be affected by Subsurface Light Transport",
 600         default=False,
 601     )
 602
 603     radio_minimum_reuse: FloatProperty(
 604         name="Minimum Reuse",
 605         description="Fraction of the screen width which sets the minimum radius of reuse "
 606         "for each sample point (At values higher than 2% expect errors)",
 607         min=0.0,
 608         max=1.0,
 609         soft_min=0.1,
 610         soft_max=0.1,
 611         default=0.015,
 612         precision=3,
 613     )
 614
 615     radio_maximum_reuse: FloatProperty(
 616         name="Maximum Reuse",
 617         description="The maximum reuse parameter works in conjunction with, and is similar to that of minimum reuse, "
 618         "the only difference being that it is an upper bound rather than a lower one",
 619         min=0.0,
 620         max=1.0,
 621         default=0.2,
 622         precision=3,
 623     )
 624
 625     radio_nearest_count: IntProperty(
 626         name="Nearest Count",
 627         description="Number of old ambient values blended together to "
 628         "create a new interpolated value",
 629         min=1,
 630         max=20,
 631         default=1,
 632     )
 633
 634     radio_normal: BoolProperty(
 635         name="Normals", description="Radiosity estimation can be affected by normals", default=False
 636     )
 637
 638     radio_recursion_limit: IntProperty(
 639         name="Recursion Limit",
 640         description="how many recursion levels are used to calculate "
 641         "the diffuse inter-reflection",
 642         min=1,
 643         max=20,
 644         default=1,
 645     )
 646
 647     radio_pretrace_start: FloatProperty(
 648         name="Pretrace Start",
 649         description="Fraction of the screen width which sets the size of the "
 650         "blocks in the mosaic preview first pass",
 651         min=0.005,
 652         max=1.00,
 653         soft_min=0.02,
 654         soft_max=1.0,
 655         default=0.04,
 656     )
 657     # XXX TODO set automatically to  pretrace_end = 8 / max (image_width, image_height)
 658     # for non advanced mode
 659     radio_pretrace_end: FloatProperty(
 660         name="Pretrace End",
 661         description="Fraction of the screen width which sets the size of the blocks "
 662         "in the mosaic preview last pass",
 663         min=0.000925,
 664         max=1.00,
 665         soft_min=0.01,
 666         soft_max=1.00,
 667         default=0.004,
 668         precision=3,
 669     )
 670
 671
 672 classes = (RenderPovSettingsScene,)
 673
 674
 675 def register():
 676     for cls in classes:
 677         register_class(cls)
 678     Scene.pov = PointerProperty(type=RenderPovSettingsScene)
 679
 680
 681 def unregister():
 682     del Scene.pov
 683     for cls in reversed(classes):
 684         unregister_class(cls)