This is a third follow-up to the thread "povray standard include files" to 
discuss development standards for a proposed area on povray.org for storage 
and distribution of a collection of objects and other files, contributed by 
the POV-Ray community. A closely associated issue raised in the original 
thread was how to maintain diversity in our scenes. The concern expressed 
was that, if many people use the same objects, the scenes that our community 
produces could become pretty repetitive.

As Sabrina has mentioned, there are certain standard ways of doing things 
that can help us to construct #include files that will work together and 
also minimise compatibility issues with future versions of POV-Ray. For 
example, using #local in include files wherever you don't need to expose 
them externally. Also starting variable names, macro names etc. that are 
exposed with an upper case letter to avoid potential conflicts with future 
POV-Ray keywords.

I think Sabrina's idea of using a unique prefix for names is a good one and 
I've used this in the past, for example, all POV-Stairs variables exposed 
externally start with SC (for StairCase). Interestingly I started using PS 
but found that someone elses include file used PS. Nevertheless, because it 
was standard I could do a case sensitive global change and was able to 
quickly change all my PS's to SC's. The lesson here is that using a standard 
makes life easier than not using a standard, even if the detail needs to 
change.

I don't think I'd agree with the idea to take naming standards to the level 
of requiring macros to contain the word 'Macro' in the name. I suspect that 
going back and retrospectively adjusting some of my own #include files would 
be cumbersome. For example, there are lots of macros in the various 
POV-Person #include files and they're mentioned all over the place in the 
documentation. Anything that needed doing to the names that couldn't be done 
with a global change would absorb lots of time (although Hungarian notation 
might work).

Florian raised the point that having a standard for sizes and names can make 
it less likely that someone put's his objects/textures/whatever in the 
collection, because it's too much hassle. Maybe a solution to this is that 
we document a standard, but don't insist people use it. We could have an 
indicator on the web site to show whether a particular submission adheres to 
the standard. This would also enable older and non-compliant files to still 
be published, but users would be forewarned about maybe having to sort out 
conflicts. From time to time we could drive campaigns to help standardise 
the most popular and well-used materials.

On the subject of Object Diversity I think we could probably come up with 
some best practices that would help people to write #include files in a 
parametrised way that permits people using the file to readily adjust as 
much as possible. For example, using #ifdef() before #declare inside the 
#include file helps someone to override default settings within their scene 
file. Rather than writing that sort of thing into our standards, I would 
propose that we assemble (or reference if some already exist) a few 
tutorials that illustrate how to build include files that enable a diverse 
range of objects to be generated.

Regards,
Chris B.

Post a reply to this message

"Chris B" <c_b### [at] btconnectcomnospam> wrote:
> A closely associated issue raised in the original
> thread was how to maintain diversity in our scenes. The concern expressed
> was that, if many people use the same objects, the scenes that our community
> produces could become pretty repetitive.

My proposal would be to have as few actual #declares as possible and instead
rely on macros to assemble components together.  This way, we'd get highly
parametrized objects/pigments/finishes/normals/color_maps etc.  It could
also benefit by encapsulation inside the macro, so that less naming
conflicts would happen.  Macros also allow far more randomness because
objects are created each time, and each time you could feed a different
"randomness" parameter or global variable to the macro...

Textures separate from shapes as well, after all, i could always want a
chrome potato instead of a boring everyday one. :)

> For example, using #local in include files wherever you don't need to expose
> them externally.

i just wish #local would also be local to macros.  oh well...

> Nevertheless, because it
> was standard I could do a case sensitive global change and was able to
> quickly change all my PS's to SC's.

in fact, this could be handled by a script server-side, by attributing
string IDs to contributions and prefixing #declares and macros
automatically.  Of course, caution should be made for not letting 2 letter
prefixes suddenly become 8-letter ones and very java like...

Still, i take it none of you want deeply nested well-organized directory
structures, ain't it true?  I really don't agree with just IDs and prefixes
and think a well-organized hierarchical directory structure for includes
should pay off in the long run.

> I don't think I'd agree with the idea to take naming standards to the level
> of requiring macros to contain the word 'Macro' in the name.

in the case of macros specifically, it seems a tradition in the povray
community to use make_foo patterns.  I like it. :)

> Florian raised the point that having a standard for sizes and names can make
> it less likely that someone put's his objects/textures/whatever in the
> collection, because it's too much hassle. Maybe a solution to this is that
> we document a standard, but don't insist people use it. We could have an
> indicator on the web site to show whether a particular submission adheres to
> the standard. This would also enable older and non-compliant files to still
> be published, but users would be forewarned about maybe having to sort out
> conflicts. From time to time we could drive campaigns to help standardise
> the most popular and well-used materials.

this all seems more of a hassle than to standardize it before submitting in
the first place. :)

Standard metrics-compliant include files could merely declare a known and
standardized flag variable to state they're compliant.

> On the subject of Object Diversity I think we could probably come up with
> some best practices that would help people to write #include files in a
> parametrised way that permits people using the file to readily adjust as
> much as possible.

heh.  I just realized indeed many people in the povray community use include
files as some sort of glorified macro, #declares as parameters and several
#includes of the same file if several "instances" of the same object is
needed.  And it really makes sense, since macros don't really come with
local scope... although kludgy...

Post a reply to this message

"nemesis" <nam### [at] gmailcom> wrote:
> Still, i take it none of you want deeply nested well-organized directory
> structures, ain't it true?  I really don't agree with just IDs and prefixes
> and think a well-organized hierarchical directory structure for includes
> should pay off in the long run.

I'm still going on the assumption that we're talking about a downloadable
..zip file containing an entire library of whatnots & widgits, so being able
to tell POV-Ray to make the whole library accessable would be really handy.
To do that, you could add all the directories and sub-directories of the
library to the master .ini file hoping that you don't exceed POV-Ray's
limit on that... (Wasn't it something like 22 directories max?  I don't
have time to check atm.) Does anybody know the reason for the limit?  Since
Chris Cason mentioned it would be possible to make minor changes before 3.7
final, I wonder how hard it would be to give .ini files the option to tell
POV-Ray to search all sub-directories of a given directory.

Or, you could keep it to a single directory like the standard INCLUDE
directory that come's with POV-Ray (requiring added emphesis on naming
conventions).  I'm with you nemesis, I'd prefer at least some hierarchy.
For one thing, not all things come in single files.  A lot of use have
whole groups of related #includes that work together as their own little
package.

One place I think naming conventions come in especially handy is in
generated files...  For instance, I've got of macros which generate meshes,
and caching equivalent meshes of varying resolutions into files comes in
really handy.  But then comes the time when I want to back up of whatever
scene directory...  Those generated files can get big!  So, I always start
their file names with "Generated_" and then use a macro to put a comment at
the top of those files saying something like "This is a generated file and
can probably be deleted without too much harm.n"  If the generated files
have uniform file names, they're pretty quick to dispose of.

Charles

Post a reply to this message

nemesis wrote:
> heh.  I just realized indeed many people in the povray community use include
> files as some sort of glorified macro, #declares as parameters and several
> #includes of the same file if several "instances" of the same object is
> needed.  And it really makes sense, since macros don't really come with
> local scope... although kludgy...

It's a practice that's carried over from before POV-Ray had macros. 
Surprisingly, after ten years, people still do it...

...Chambers

Post a reply to this message

Chris B wrote:
> collection, because it's too much hassle. Maybe a solution to this is that 
> we document a standard, but don't insist people use it.

That's worse than having no standard, because then you have to check 
whether or not its standardized...

My opinion is, you make a standard, and stick to your guns.  People are 
still free to make their own files, and distribute them the 
old-fashioned way, so noone's really losing anything.  But for such a 
collection to be useful, standards are the way to go.

That being said, I think a few basic standards should be enough:
1) Each include file deals with only one object / texture / function / 
whatever (see #5 below for an exception).
2) No hard-coded sizes, everything must be parameterized.
3) All items should be generated by a macro for consistency.  If all 
you're doing is declaring a texture, still generate it by macro to match 
the consistency of everything else in the archive.
4) The name of said macro should be identical to the file name, but for 
heaven's sake, avoid Hungarian notation like the plague it is!
5) Where it makes sense, objects that can take advantage of 
randomization should come in two flavors: a basic one, with no 
randomization, and a random one (append the macro with _r if you must) 
which accepts as an additional argument, a random number stream.  This 
allows you to use your own random streams in the object creation process.

I think that's everything; at least, I can't think of anything else off 
the top of my head.

...Chambers

Post a reply to this message

Chris B wrote:

> As Sabrina has mentioned, there are certain standard ways of doing things 
> that can help us to construct #include files that will work together and 
> also minimise compatibility issues with future versions of POV-Ray. For 
> example, using #local in include files wherever you don't need to expose 
> them externally. Also starting variable names, macro names etc. that are 
> exposed with an upper case letter to avoid potential conflicts with future 
> POV-Ray keywords.

This is something that C/C++ programmers (and others as well) know: 
Don't use globals unless you really, really have to.

> I think Sabrina's idea of using a unique prefix for names is a good one and 
> I've used this in the past, for example, all POV-Stairs variables exposed 
> externally start with SC (for StairCase). Interestingly I started using PS 
> but found that someone elses include file used PS. Nevertheless, because it 
> was standard I could do a case sensitive global change and was able to 
> quickly change all my PS's to SC's. The lesson here is that using a standard 
> makes life easier than not using a standard, even if the detail needs to 
> change.

I already do this with my Subdivision Surface macros; everything starts 
with SSS or sss.

> Florian raised the point that having a standard for sizes and names can make 
> it less likely that someone put's his objects/textures/whatever in the 
> collection, because it's too much hassle. Maybe a solution to this is that 
> we document a standard, but don't insist people use it. We could have an 
> indicator on the web site to show whether a particular submission adheres to 
> the standard. This would also enable older and non-compliant files to still 
> be published, but users would be forewarned about maybe having to sort out 
> conflicts. From time to time we could drive campaigns to help standardise 
> the most popular and well-used materials.

Probably the biggest issue is that while many people around here use 1 
unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.

This is probably best addressed with a simple line at the start of the 
macro or scene file:

// -- uses centimeter scaling

> On the subject of Object Diversity I think we could probably come up with 
> some best practices that would help people to write #include files in a 
> parametrised way that permits people using the file to readily adjust as 
> much as possible. For example, using #ifdef() before #declare inside the 
> #include file helps someone to override default settings within their scene 
> file. Rather than writing that sort of thing into our standards, I would 
> propose that we assemble (or reference if some already exist) a few 
> tutorials that illustrate how to build include files that enable a diverse 
> range of objects to be generated.

Well, I use an #ifndef-#local-#end block, and it works fine.  My robot 
models have a default texture for different things; in fact, there is 
also a BotGender variable that specifies which of two defaults gets used.

And we can put code in the #ifndef-#local-#end block to detect if any of 
the defaults are changed, and print out "Use some imagination!" if none 
of them are changed :-)

Regards,
John

Post a reply to this message

John VanSickle <evi### [at] hotmailcom> wrote:

> Probably the biggest issue is that while many people around here use 1
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
>
> This is probably best addressed with a simple line at the start of the
> macro or scene file:
>
> // -- uses centimeter scaling

John, this is a good point.  However, in a rendered scene, all real-world
metrics are virtual and exist only in the mind of the author of the scene
or that of the viewer.

The only immutable metric in a rendered scene is the pixel.  For purely
technical purposes, what if the objects in publicly shared include files
are initially intended to be viewable in a scene with an 'orthographic
camera' with 'up' and 'right' vectors which correspond to a standardized
render window - say < 0, 480, 0> and < 640, 0, 0 > respectively?

That way, when the end user makes use of one of these objects, s/he can
calculate centimeter/pixel, meter/pixel, inch/pixel, etc. at some distance
from the camera they're using and scale the objects accordingly.  Of
course, if rendering an image with dimensions other than 640 x 480 ( my
usual preference ), then scaling would also have to reflect this as well.

Post a reply to this message

Ben Chambers <ben### [at] pacificwebguycom> wrote:

> That's worse than having no standard, because then you have to check
> whether or not its standardized...
>
> My opinion is, you make a standard, and stick to your guns.  People are
> still free to make their own files, and distribute them the
> old-fashioned way, so noone's really losing anything.  But for such a
> collection to be useful, standards are the way to go.


I think it all depends on what we're building here.  Something like a
professonal product containing the best of the best, or a community effort
containing some things that might not be as up-to-snuff as others.  If this
were a for-sale package, it'd be most professional to have everything be as
uniform as possible.  On the other hand, if it were up to me I'd like to
think of this thing to be a little more inclusive.  I think we'll be hard
pressed to find a single standard that won't turn most people away.  So,
I'd lean more towards guidelines, and tutorials on how to make #includes
"nice," kinda like what Chris B was talking about.

Charles

Post a reply to this message

John VanSickle <evi### [at] hotmailcom> wrote:

> Probably the biggest issue is that while many people around here use 1
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.
>
> This is probably best addressed with a simple line at the start of the
> macro or scene file:
>
> // -- uses centimeter scaling

Heh, I use different measurement systems depending on what seems appropriete
for the thing I'm making.  I've said it in another post, but I do think that
scaling (& re-orienting) objects to fit your scene is just a fact of life.

BTW, I do also tend to use 1cm = 1 unit.

Post a reply to this message

From: Charles C
> Since Chris Cason mentioned it would be possible to make minor changes before 3.7
> final, I wonder how hard it would be to give .ini files the option to tell
> POV-Ray to search all sub-directories of a given directory."

I also have a suggestion, now that we're at it:  is it much hard to give
macros proper local scope for #local variables?  If it is, i guess the
practice of using the whole include file as a big macro will carry on...

From: Charles C
> I'd prefer at least some hierarchy.

Keywords are cool for searching, but not for organizing code.  Chris B
suggested having few main areas of interest as high-level branches and i'm
with him.  I'd also suggest each contributor having a short prefix
associated, so if, say, nem or chc both contribute cedar textures, it
should come like this:
textures/wood/nem_cedar.inc
textures/wood/chc_cedar.inc

or something.  The prefix would be automatically generated by a server-side
script taking into account the contributor's login or email or something.

From: Ben Chambers
>That's worse than having no standard, because then you have to check
> whether or not its standardized...
> My opinion is, you make a standard, and stick to your guns.  People are
> still free to make their own files, and distribute them the
> old-fashioned way, so noone's really losing anything.  But for such a
> collection to be useful, standards are the way to go."

I wholeheartdly agree.  People may or may not use the proposed standard and
may or may not benefit from it.  Nobody loses and people wanting a
standard gain a lot from it.

I proposed having a flag variable declared in each include file following
the standard, something like:

#declare USE_STD = yes;

Include files not following it simply don't have such flag and scenes
including the files can check if they follow the standard or not, like:

#include "landscapes/desert/nem_sand.inc"
#ifdef( USE_STD )
......
  #undef USE_STD // <- important!
#else
......
#end

From: Ben Chambers
> 1) Each include file deals with only one object / texture / function /
whatever (see #5 below for an exception).

fine by me

> 2) No hard-coded sizes, everything must be parameterized.

I don't think a default size would be bad, specially if we are able to
standardize the metrics.  Still, this is povray we're talking about, where
potatoes can be 50 meters tall and have chrome texture! :)

On the subject of sizes i believe it'd be good if people took their time to
scale contributed objects to fit either height or width to 1 unit, whatever
it is.  Because then, if i want it to have a 3 meter paper clip, i simply
scale it like "scale x*3" given the 1 unit fitting scheme used the width of
the object.

While we're at it, we live in a gravity centered world and generally objects
are not floating around, but lying into yet other objects.  I'd suggest
placing objects upon the origin, that is, the common bottom of the object
resting in y*0.  Like chairs resting on their feet or an egg lying to its
side.

> 3) All items should be generated by a macro for consistency.  If all
> you're doing is declaring a texture, still generate it by macro to match
> the consistency of everything else in the archive.

exactly!  and it brings composition and some randomness to the forefront.

> 4) The name of said macro should be identical to the file name, but for
> heaven's sake, avoid Hungarian notation like the plague it is!

for macros, the make_foo pattern is cool enough.  But personally, i
generally go for t_tex1, fn_fin1, p_pig1, n_nor1 and the likes for other
name patterns... I'd have to change to more closely match the CamelCase
style used by most povvers. :)

> 5) Where it makes sense, objects that can take advantage of
> randomization should come in two flavors: a basic one, with no
> randomization, and a random one (append the macro with _r if you must)
> which accepts as an additional argument, a random number stream.  This
> allows you to use your own random streams in the object creation process.

very good!

what about a level-of-detail parameter?  like, 1,2,3 for basic, medium,
complex?  or is it too much?  am i thinking too much ahead?

From: John VanSickle
> I already do this with my Subdivision Surface macros; everything starts
> with SSS or sss.

oh noes!  what about macros dealing with SubSurface Scattering?! ;)

> Probably the biggest issue is that while many people around here use 1
> unit = 1 meter, others (such as I) use 1 unit = 1 cm for most scenes.

how about:
#declare UNIT = m;
or
#declare UNIT = cm;

as a way to explicitely declare your intentions for standard-compliant
scenes?

> And we can put code in the #ifndef-#local-#end block to detect if any of
> the defaults are changed, and print out "Use some imagination!" if none
> of them are changed :-)

lovely idea! :)

From: Randall Sawyer
> in a rendered scene, all real-world
> metrics are virtual and exist only in the mind of the author of the scene
> or that of the viewer.

yes, but nothing should prevent the author of putting some default in there
and people from using such default.

> what if the objects in publicly shared include files
> are initially intended to be viewable in a scene with an 'orthographic
> camera' with 'up' and 'right' vectors which correspond to a standardized
> render window - say < 0, 480, 0> and < 640, 0, 0 > respectively?

I think this is out of scope in the discussion, because we're talking about
metrics, size and placement standardization.  hopefully, lighting standards
could also come by...

yes, people viewing an object up close or very far away will have no notion
of metrics involved.  But the metrics standard should not be there for an
object alone, but to correctly relate it to other objects following such
standard.


From: Charles C
> I think we'll be hard
> pressed to find a single standard that won't turn most people away.

How something optional like the metrics standard could possibly turn people
away?  I say, let people wanting a metric standard to discuss metric
standard matters, let people wanting to address other issues address other
issues and let people just wanting to contribute something they created
contribute it without any metrics consideration whatsoever.

Post a reply to this message