OK, I'm either doing something phenomenally stupid, or there's a blatant bug 
in isosurface{} in 3.7rc3.

Step 1) Consider the following simple scene:


  #version 3.7;
  global_settings { assumed_gamma 2.2 }

  camera{ location 5 look_at 0 right x*4/3 }
  light_source{<2,4,8>, <1, .8, .6> }

  sky_sphere {pigment {gradient -y}}

  #declare clipper = difference {box {-2 2} box {<0,-3,0> 3}}
  object {clipper pigment {rgbft <0,1,1,.2,.2>} }


I'm declaring an object and displaying it. It is a box with one quarter 
taken out. I'm calling it "clipper" because I want to use it to clip another 
object.

Step 2) Now add the following object:

  sphere {0 2 pigment {rgb 1}}

Since 'clipper' is parially transparent, you can see the back 3/4 though it 
with the front quarter exposed.

Step 3) use 'clipper' to clip the sphere, i.e. modify the 'sphere' object 
like this:

  sphere {0 2 clipped_by {clipper} pigment {rgb 1}}

The front part of the sphere is now clipped away by the 'clipper' box, but 
the rest can still be seen in the box. Note the shadow cast by the front 
right edge of the sphere onto/into the inside of the sphere.

Step 4) Remove the line that shows the clipper box:

  // object {clipper ....

You can now see the (hollow) back 3/4 of a sphere with the opening pointing 
at you. You can still see the aforementioned shadow.

So far this is all as I would expect it.

HOWEVER: now do the same thing again, but in step (2), instead of the 
sphere{} put this simple isosurface instead:

  isosurface{function{ sqrt(x*x+y*y+z*z) }
        threshold 2 max_gradient 100 contained_by{ box {-5 5} }
     //     clipped_by { clipper }
          pigment {rgb 1}
        }

In steps (2) and (3) I see the exact same thing that I see with the sphere 
object. In particular I can see the shadow on step (3) that tells me that I 
can see the inside/backside of the isosurface.

But in step 4, the back/inside of the isosurface is gone.

Why?

Post a reply to this message

Le 18/05/2011 02:46, SGeier a écrit :
> OK, I'm either doing something phenomenally stupid, or there's a blatant bug 
> in isosurface{} in 3.7rc3.

Have you tried it with 3.6 ?

> Why?

I would not use clipped_by to perform CSG intersection.


-- 
Software is like dirt - it costs time and money to change it and move it
around.

Just because you can't see it, it doesn't weigh anything,
and you can't drill a hole in it and stick a rivet into it doesn't mean
it's free.

Post a reply to this message

"SGeier" <som### [at] somewherecom> wrote:
>   isosurface{function{ sqrt(x*x+y*y+z*z) }
>         threshold 2 max_gradient 100 contained_by{ box {-5 5} }
>      //     clipped_by { clipper }
>           pigment {rgb 1}
>         }
>
> In steps (2) and (3) I see the exact same thing that I see with the sphere
> object. In particular I can see the shadow on step (3) that tells me that I
> can see the inside/backside of the isosurface.
>
> But in step 4, the back/inside of the isosurface is gone.
>
> Why?

Because you did not read the manual.

See http://www.povray.org/documentation/view/3.6.1/300/

Thorsten

Post a reply to this message

On 05/18/2011 06:55 AM, Thorsten Froehlich wrote:
> "SGeier"<som### [at] somewherecom>  wrote:
>>    isosurface{function{ sqrt(x*x+y*y+z*z) }
>>          threshold 2 max_gradient 100 contained_by{ box {-5 5} }
>>       //     clipped_by { clipper }
>>            pigment {rgb 1}
>>          }
>>
>> In steps (2) and (3) I see the exact same thing that I see with the sphere
>> object. In particular I can see the shadow on step (3) that tells me that I
>> can see the inside/backside of the isosurface.
>>
>> But in step 4, the back/inside of the isosurface is gone.
>>
>> Why?
>
> Because you did not read the manual.
>
> See http://www.povray.org/documentation/view/3.6.1/300/
>
> Thorsten
>
>
>
hmmm ... I didn't spot the clue. I'm tempted to say the use of or size 
clipper ... care to offer another hint ;-)

Post a reply to this message

Jim Holsenback <jho### [at] povrayorg> wrote:
> On 05/18/2011 06:55 AM, Thorsten Froehlich wrote:
> > "SGeier"<som### [at] somewherecom>  wrote:
> >>    isosurface{function{ sqrt(x*x+y*y+z*z) }
> >>          threshold 2 max_gradient 100 contained_by{ box {-5 5} }
> >>       //     clipped_by { clipper }
> >>            pigment {rgb 1}
> >>          }
> >>
> >> In steps (2) and (3) I see the exact same thing that I see with the sphere
> >> object. In particular I can see the shadow on step (3) that tells me that I
> >> can see the inside/backside of the isosurface.
> >>
> >> But in step 4, the back/inside of the isosurface is gone.
> >>
> >> Why?
> >
> > Because you did not read the manual.
> >
> > See http://www.povray.org/documentation/view/3.6.1/300/
> >
> > Thorsten
> >
> >
> >
> hmmm ... I didn't spot the clue. I'm tempted to say the use of or size
> clipper ... care to offer another hint ;-)

The hint about CSG and isosurfaces is at the very end of that page ;-)

Thorsten

Post a reply to this message

"Thorsten Froehlich" <nomail@nomail> wrote in message 
news:web.4dd3aa7c955938cce619b42c0@news.povray.org...
> Jim Holsenback <jho### [at] povrayorg> wrote:
>> On 05/18/2011 06:55 AM, Thorsten Froehlich wrote:
>> > "SGeier"<som### [at] somewherecom>  wrote:
[...]
>> >> In steps (2) and (3) I see the exact same thing that I see with the 
>> >> sphere
>> >> object. In particular I can see the shadow on step (3) that tells me 
>> >> that I
>> >> can see the inside/backside of the isosurface.
>> >>
>> >> But in step 4, the back/inside of the isosurface is gone.
>> >>
>> >> Why?
>> >
>> > Because you did not read the manual.
>> >
>> > See http://www.povray.org/documentation/view/3.6.1/300/
>> >
>> > Thorsten
>> >
>> >
>> >
>> hmmm ... I didn't spot the clue. I'm tempted to say the use of or size
>> clipper ... care to offer another hint ;-)
>
> The hint about CSG and isosurfaces is at the very end of that page ;-)
>
> Thorsten

*IF* you are making reference to this sentence:

  "By default POV-Ray searches only for the first surface which the ray 
intersects. But when using an isosurface in CSG operations, the other 
surfaces must also be found. Therefore, the keyword max_trace must be added 
to the isosurface statement. It must be followed by an integer value.

*THEN* I'd like to point out that this sentence is false:
- The back-side of the isosurface IS the first surface the ray intersects 
after the sphere is clipped.
- It is in fact found when the 'clipper' object is visible.

It only vanishes after I turn off the clipper object. Even though it is 
still the first surface of the sphere that the viewing-ray intersects 
(because all surfaces "in front of it" are clipped). Nothing has changed 
about the sphere or which of its surfaces should or should not be 
intersected by the viewing ray; all that has changed is that I made the 
clipper-volume invisible.

Of course there is no reason why 3.7 should conform to the 3.6 
documentation. Which makes it a bit disingenous to point people to the 3.6 
docs when they ask questions about 3.7 regarding behaviour *that is 
definitely in conflict with the 3.6 documentation*.

Post a reply to this message

On 18.05.11 21:00, SGeier wrote:
> *IF* you are making reference to this sentence:
>
>    "By default POV-Ray searches only for the first surface which the ray
> intersects. But when using an isosurface in CSG operations, the other
> surfaces must also be found. Therefore, the keyword max_trace must be added
> to the isosurface statement. It must be followed by an integer value.
>
> *THEN* I'd like to point out that this sentence is false:

The sentence is true and correct for 3.6 as well as 3.7. What is wrong is 
your interpretation of what you are seeing without knowing the inner 
workings of POV-Ray by making assumptions about the inner workings that are 
false.

> Of course there is no reason why 3.7 should conform to the 3.6
> documentation.

You can be certain POV-Ray conforms to this part of the documentation, be it 
3.6 or 3.7.

> Which makes it a bit disingenous to point people to the 3.6
> docs when they ask questions about 3.7 regarding behaviour *that is
> definitely in conflict with the 3.6 documentation*.

No.

It certainly helps to read the documentation when being pointed to it, 
rather than complain about being helped ... add all_intersections and just 
be happy.

	Thorsten

Post a reply to this message

Am 18.05.2011 21:00, schrieb SGeier:

> *IF* you are making reference to this sentence:
>
>    "By default POV-Ray searches only for the first surface which the ray
> intersects. But when using an isosurface in CSG operations, the other
> surfaces must also be found. Therefore, the keyword max_trace must be added
> to the isosurface statement. It must be followed by an integer value.
>
> *THEN* I'd like to point out that this sentence is false:

Well, actually it's not.

> - The back-side of the isosurface IS the first surface the ray intersects
> after the sphere is clipped.

The catch is that the back side may be the first surface of the 
isosurface /within the clipped_by object/ - but /not/ the first surface 
of the isosurface /per se/ - which the ray intersects.

clipped_by is implemented as follows:

(1) The base object's intersection(s) with the ray are determined;

(2) for each intersection it is checked whether it is inside the 
clipped_by object.

Any intersections not reported by step (1) are ignored.

> - It is in fact found when the 'clipper' object is visible.
>
> It only vanishes after I turn off the clipper object. Even though it is
> still the first surface of the sphere that the viewing-ray intersects
> (because all surfaces "in front of it" are clipped). Nothing has changed
> about the sphere or which of its surfaces should or should not be
> intersected by the viewing ray; all that has changed is that I made the
> clipper-volume invisible.

Note that strictly speaking the object you're making (in)visible is 
/not/ the clipped_by object; rather, the two are independent objects 
that just happen to be derived from the same "prototype" object (your 
"clipper" object).

Once the ray hits the surface of a partially transparent object, a new 
ray is shot from that intersection point in the same direction as the 
original ray; with this intersection point being /inside/ the 
(non-clipped) isosurface, the back side now is /truly/ the first surface 
of the isosurface the ray intersects.

Again, note that the clipped_by object is /not/ a full-fledged scene 
object; POV-Ray never performs any intersection tests on it when 
shooting rays - it is /exclusively/ used to check whether an 
already-found intersection is inside of it.

> Of course there is no reason why 3.7 should conform to the 3.6
> documentation. Which makes it a bit disingenous to point people to the 3.6
> docs when they ask questions about 3.7 regarding behaviour *that is
> definitely in conflict with the 3.6 documentation*.

That's quite a *bold* statement (in any sense, including typographic); 
please be aware that /sometimes/ the developers do know POV-Ray better 
than the average user ;-)

I'd agree that Thorsten may not be the best diplomat - but technically 
he's right: The behaviour you're observing may be surprising, but works 
as intended. Maybe the wording in the docs isn't ideal, but aside from 
that there's nothing wrong.

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd45e2b@news.povray.org...
> Am 18.05.2011 21:00, schrieb SGeier:
>
>> *IF* you are making reference to this sentence:
>>
>>    "By default POV-Ray searches only for the first surface which the ray
>> intersects. But when using an isosurface in CSG operations, the other
>> surfaces must also be found. Therefore, the keyword max_trace must be 
>> added
>> to the isosurface statement. It must be followed by an integer value.
>>
>> *THEN* I'd like to point out that this sentence is false:
>
> Well, actually it's not.
>
>> - The back-side of the isosurface IS the first surface the ray intersects
>> after the sphere is clipped.
>
> The catch is that the back side may be the first surface of the isosurface 
> /within the clipped_by object/ - but /not/ the first surface of the 
> isosurface /per se/ - which the ray intersects.
>
> clipped_by is implemented as follows:
>
> (1) The base object's intersection(s) with the ray are determined;
>
> (2) for each intersection it is checked whether it is inside the 
> clipped_by object.
>
> Any intersections not reported by step (1) are ignored.

Good to know that this is how it is implemented. However this is NOT how it 
is documented. Put the above paragraph into the documentation and 
implementation and documentation are in agreement.

[...]
>> Of course there is no reason why 3.7 should conform to the 3.6
>> documentation. Which makes it a bit disingenous to point people to the 
>> 3.6
>> docs when they ask questions about 3.7 regarding behaviour *that is
>> definitely in conflict with the 3.6 documentation*.
>
> That's quite a *bold* statement (in any sense, including typographic); 
> please be aware that /sometimes/ the developers do know POV-Ray better 
> than the average user ;-)

I would hope so - that's why I post things here that do not work as 
documented.

There's a perennial communications problem between programmers and users: To 
the programmer, the code is the end-all and be-all. Whatever the code does 
is "true" and if the documentation deviates from it, then the documetation 
is wrong. However from the user perspective, the documentation is all there 
is - it tell me what is *supposed* to happen and if the observed results are 
different then the code is buggy.

I'm happy to go either way - but there IS still a mismatch between 
implementation and documentation here.

> I'd agree that Thorsten may not be the best diplomat - but technically 
> he's right: The behaviour you're observing may be surprising, but works as 
> intended.

To a user of POV-Ray it does not (can not) matter what the programmers 
*intended*. Unless you want every single one of us folks out here to come 
here and post so that you can explain every single one of us what you 
intended. The only thing that *can* matter to us is what is *documented*.

> Maybe the wording in the docs isn't ideal, but aside from that there's 
> nothing wrong.

If the wording in the docs leads the reader to expect behaviour different 
from what is implemented, then the wording is far enough from ideal that we 
might as well call it false. No part of the documentation indicates that the 
back/inside of the isosurface object will be found when the outer clipping 
object is made visible (or the clipped object embedded into a transparent 
object or any such thing). In the case of the sphere object, it is visible 
in both cases, in the case of the isosurface object it is visible in the 
one, but not the other case.

If that is "as intended", then this intention needs to be communicated (in 
the docs, not here).
Which it isn't.

Post a reply to this message

On 05/19/2011 12:06 AM, SGeier wrote:
> If that is "as intended", then this intention needs to be communicated (in
> the docs, not here).
> Which it isn't.

if you think it's /that/ out of whack then ... get yourself a login on 
the wiki and edit the section to your liking ... i'll even meet you 
halfway. i've copied the aforementioned section into a talk page so have 
at it

http://wiki.povray.org/content/Documentation_Talk:Reference_Section_4.2

Post a reply to this message

Am 19.05.2011 05:06, schrieb SGeier:

>> clipped_by is implemented as follows:
>>
>> (1) The base object's intersection(s) with the ray are determined;
>>
>> (2) for each intersection it is checked whether it is inside the
>> clipped_by object.
>>
>> Any intersections not reported by step (1) are ignored.
>
> Good to know that this is how it is implemented. However this is NOT how it
> is documented. Put the above paragraph into the documentation and
> implementation and documentation are in agreement.

If you think the documentation is bad, then you're happily invited to 
help make it better.

It's not like the developers & other people helping with POV-Ray would 
be paid anything for it; our only payment is the joy of doing it (and 
every programmer knows that implementation work is more fun than writing 
documentation), the joy of seeing people get good results of it, and the 
joy of receiving some motivating feedback from the community now and then.

So if you /want/ anything from us, or want to /insist/ on some point of 
view that the dev team does not share, you're in the wrong place.

> I would hope so - that's why I post things here that do not work as
> documented.

It's one thing to get feedback on things that people /think/ is wrong. 
Getting feedback from someone who /knows better/ (or at least sounds 
like that) is something entirely different.

> There's a perennial communications problem between programmers and users: To
> the programmer, the code is the end-all and be-all. Whatever the code does
> is "true" and if the documentation deviates from it, then the documetation
> is wrong. However from the user perspective, the documentation is all there
> is - it tell me what is *supposed* to happen and if the observed results are
> different then the code is buggy.

No. To the programmer, the /intention/ is the end-all and be-all. If the 
code fails to match that, it is buggy. If the documentation fails to 
match that, it is either wrong (making an explicit statement that is not 
true), incomplete (failing to make an explicit statement that is true 
bot not necessarily obvious to the user), or imprecise (making a 
statement that can be interpreted in a way that is true, but also in 
another way that is not).

In this particular case, the documentation is /incomplete/, but not 
wrong: It does /not/ make an explicit statement about the situation you 
encountered. It does however make a statement about similar situations 
with CSG, which /might/ give resourceful users a hint what's going wrong 
with regard to clipped_by.


BTW, to the end user, the /expectation/ is the end-all and be-all; the 
documentation can only serve to modify those expectations. So if some 
docs do not explicitly mention the program's behaviour in a very rare 
situation, who is outright /wrong/: The documentation, or the user's 
expectations? I dare say the latter, because the docs simply cannot 
foresee all that a user may expect.

Also note that in real life there is no such thing as a /complete/ 
documentation.

> If the wording in the docs leads the reader to expect behaviour different
> from what is implemented, then the wording is far enough from ideal that we
> might as well call it false.

I disagree in some points:

(1) The docs do not /lead/ the reader to expect behaviour different from 
what is implemented in this case. It is /your/ expectation, and all you 
can blame the documentation for is that it did not /lead you away/ from 
that expectation. Provided that you even gave it a chance to do so, by 
thoroughly reading the isosurfaces doc section.

(2) I guess that careful reading of the doc section on isosurfaces 
/will/ lead the majority of readers away from that expectation, at least 
to the degree that they're not too surprised when their original 
expectation proves wrong.

(3) My definition of a "false" documentation is more strict than yours 
seems to be. In my terminology, "incomplete" or "imprecise" is not 
necessarily "false".


> If that is "as intended", then this intention needs to be communicated (in
> the docs, not here).

(4) There is no /need/ to communicate the programmers' intentions to the 
users. It's probably /helpful/, but there is no such /obligation/ to the 
dev team - neither legally (see the license) nor morally (what you get 
from the dev team is a free gift, and you can either take it or leave 
it, and there's nothing you can /demand/ on top).

Post a reply to this message

"Thorsten Froehlich" <tho### [at] trfde> wrote in message 
news:4dd41abd@news.povray.org...
> On 18.05.11 21:00, SGeier wrote:
>
> It certainly helps to read the documentation when being pointed to it, 
> rather than complain about being helped

It /also/ certainly helps to try a non-functioning case of code when being 
pointed to it, rather than complain about being helped. Because that's what 
*I'm* doing when I point out things that don't work: help you. By either 
alerting you to buggy code (code that does not work as intended) or buggy 
documentation (documentation that does not communicate how things are 
intended to work).

>... add all_intersections and just be happy.

Why don't you try it yourself?

Seriously: Why not?

I gave you the best bug-report I can think of writing; with a few discrete 
steps where I describe at each step why I am taking it, what I expect to see 
and what I actually see.

What do I have to do to motivate you to simply follow along with my example, 
see for yourself where things stop working - and then enter that line and 
see it /start/ working. Wouldn't that give you satisfaction? Why are you so 
afraid of simply trying it? What do you have to lose here?

Let me save you typing effort and reproduce the whole file so you can just 
cut/paste it:

// --------------------start here
  #version 3.7;
  global_settings { assumed_gamma 2.2 }

  camera{ location 5 look_at 0 right x*4/3 }
  light_source{<2,4,8>, <1, .8, .6> }

  sky_sphere {pigment {gradient -y}}

  #declare clipper = difference {box {-2 2} box {<0,-3,0> 3}}

  isosurface{function{ sqrt(x*x+y*y+z*z) }
        threshold 2 max_gradient 100 contained_by{ box {-5 5} }
          clipped_by { clipper }
          pigment {rgb 1}
          all_intersections
        }
//--------------------end here

See: I have the best documentation there is: the program itself. Whatever 
the program does is whatever it does. You may /imagine/ that you know it 
better than me, but I've actually looked at it. I get to see the actual 
binary, produced by compiler 'x', using library 'y' interacting with OS 'z'. 
(OS'es are Windows Server.03 32bit and and Server.08 64bit just in case 
anybody really cares).

Post a reply to this message

Am 19.05.2011 20:47, schrieb SGeier:

> Let me save you typing effort and reproduce the whole file so you can just
> cut/paste it:
>
> // --------------------start here
>    #version 3.7;
>    global_settings { assumed_gamma 2.2 }
>
>    camera{ location 5 look_at 0 right x*4/3 }
>    light_source{<2,4,8>,<1, .8, .6>  }
>
>    sky_sphere {pigment {gradient -y}}
>
>    #declare clipper = difference {box {-2 2} box {<0,-3,0>  3}}
>
>    isosurface{function{ sqrt(x*x+y*y+z*z) }
>          threshold 2 max_gradient 100 contained_by{ box {-5 5} }
>            clipped_by { clipper }
>            pigment {rgb 1}
>            all_intersections
>          }
> //--------------------end here
>
> See: I have the best documentation there is: the program itself. Whatever
> the program does is whatever it does. You may /imagine/ that you know it
> better than me, but I've actually looked at it. I get to see the actual
> binary, produced by compiler 'x', using library 'y' interacting with OS 'z'.
> (OS'es are Windows Server.03 32bit and and Server.08 64bit just in case
> anybody really cares).

You didn't actually /try/ the code you posted, did you? Otherwise you'd 
have noticed that above code does not support your point at all, but 
instead just gives a parse error.

all_intersections needs to go before the clipped_by statement. That, by 
the way, is in the docs, too.

Once you place all_intersections at the /right/ place everything /will/ 
be fine.

You're complaining that Thorsten did not try out the code you posted - 
but why should he, if he knows POV-Ray good enough (and yes, obviously 
better than you) that he's not in the least surprised, and can even tell 
you /why/ it is happening? (Besides, what makes you so sure that he 
didn't try it?)

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd5a5ed$1@news.povray.org...
> Am 19.05.2011 20:47, schrieb SGeier:
>
>> Let me save you typing effort and reproduce the whole file so you can 
>> just
>> cut/paste it:
>>
>> // --------------------start here
>>    #version 3.7;
>>    global_settings { assumed_gamma 2.2 }
>>
>>    camera{ location 5 look_at 0 right x*4/3 }
>>    light_source{<2,4,8>,<1, .8, .6>  }
>>
>>    sky_sphere {pigment {gradient -y}}
>>
>>    #declare clipper = difference {box {-2 2} box {<0,-3,0>  3}}
>>
>>    isosurface{function{ sqrt(x*x+y*y+z*z) }
>>          threshold 2 max_gradient 100 contained_by{ box {-5 5} }
>>            clipped_by { clipper }
>>            pigment {rgb 1}
>>            all_intersections
>>          }
>> //--------------------end here
>>
>> See: I have the best documentation there is: the program itself. Whatever
>> the program does is whatever it does. You may /imagine/ that you know it
>> better than me, but I've actually looked at it. I get to see the actual
>> binary, produced by compiler 'x', using library 'y' interacting with OS 
>> 'z'.
>> (OS'es are Windows Server.03 32bit and and Server.08 64bit just in case
>> anybody really cares).
>
> You didn't actually /try/ the code you posted, did you?

Yes, I did. Noting that this doesn't work.

> Otherwise you'd have noticed that above code does not support your point 
> at all, but instead just gives a parse error.

Indeed, it does. Which I noticed. Which is why I was trying to coax Thorsten 
Froehlich into trying his own suggestion. Which was this:

> add all_intersections and just be happy.

Which does not work. Thank you for trying it. Thank you for noticing that 
*the advice given by people who know the program so well DOES NOT WORK*.

> all_intersections needs to go before the clipped_by statement.

Thank you for pointing that out. Always pleased to learn something.

> That, by the way, is in the docs, too.

No, it is not.

This is exactly where our views on the documentation differ drastically. 
Yes, now that you mention it, I can see how one *could* read the 
documentation such as to suggest that. However it *definitely* does not 
contain the sentence

"all_intersections needs to go before the clipped_by statement."

or any sentence anywhere close to it.

Here's what section 3.4.4 of the documentation shipping with the windows 
verion *actually* says:
isosurface {
  function { FUNCTION_ITEMS }
  [contained_by { SPHERE | BOX }]
  [threshold FLOAT_VALUE]
  [accuracy FLOAT_VALUE]
  [max_gradient FLOAT_VALUE]
  [evaluate P0, P1, P2]
  [open]
  [max_trace INTEGER] | [all_intersections]
  [OBJECT_MODIFIERS...]
  }
This tells me that a number of items can occur inside the isosurface{} 
entity. For example [threshold ...] or [contained_by ...] and a whole class 
of [object modifiers]. Nowhere in the docs is any mention that their order 
matters in any way and as a matter of fact some of the examples in the 
tutorial have them in an order different from the above.

If the [object modifiers] have a special status here, in that they *have* to 
be at any one particular place (at the end), then that needs to be spelled 
out. If it isn't spelled out, then you cannot claim that it is in the docs.

Here is a place where the documentation might not be in direct contradiction 
with the behavior of the program, but the program certainly doesn't behave 
as documented. [all_intersections] can apparently go anywhere it wants in 
that list up there *except* after [object modifiers] -- and users are 
supposed to magically know that even though it is definitely NOT written 
anywhere.

And when someone like myself complains about the documentation we're being 
told that we should improve it. But of course we *cannot* improve it since 
there is no way to find out what the real behaviour actually *is*, since the 
documentation doesn't mention it and asking on usenet gets me helpful advice 
like

> add all_intersections and just be happy.

which I had seen, tried, and noticed it didn't work. So I figured that 
something changed since the docs were written, so I post here.

So it turns out the whole thing was *really* not about clipping at all, all 
the blah-blah about reading the documentation on clipping and max_trace and 
all_intersections was completely besides the point. Apparently neither you 
nor Thorsten had the slightest idea what was wrong, you just immediately 
assumed that *obviously* I hadn't read the documentation and *obviously* you 
know exactly what's going on, no need to actually investigate anything or 
think about anything.

Cool, so there's nothing wrong with the binary, it's the documentation that 
is unclear. Good to know.

Now why is it like pulling teeth to get someone to actually come out and 
examine things and state these things here on the ng? Until I posted the few 
lines there in toto, nobody around here had even *tried* to diagnose what my 
problem might be -- you all just assumed you knew exactly what the problem 
was (and it turned out to be somewhere else).

> You're complaining that Thorsten did not try out the code you posted - but 
> why should he, if he knows POV-Ray good enough (and yes, obviously better 
> than you) that he's not in the least surprised, and can even tell you 
> /why/ it is happening? (Besides, what makes you so sure that he didn't try 
> it?)

Because his answer "add this line to your SDL and it'll all work" did NOT 
work. Either he doesn't know POV-Ray as well as you both think, or he knows 
it *too* well, where he's not stating what assumptions *he* is making (which 
is exactly what I find myself accused of).

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd541fb@news.povray.org...
> Am 19.05.2011 05:06, schrieb SGeier:
>
> If you think the documentation is bad, then you're happily invited to help 
> make it better.

I am honestly not being facetious when I (honestly, serious!) ask: How is 
that supposed to work, when I don't know how POV-Ray works? I look into the 
documentation when something doesn't work as I expect. I learn something, 
try something, and realize it doesn't work as written in the docs either. 
How on earth am I supposed to now suddenly write better docs?

I've been poking my head into POV-Ray for several years now - I d/l the 
current version, I tinker with it, I give up. Because every time I run into 
the same kinds of problems that aren't documented and when I ask about them 
nobody takes the time to examine what was communicated how in the docs and 
when I complain about the docs I'm being told that I'm free to make them 
better. But how should I do that, when I don't even understand some very 
basic, simple things about POV-Ray *because they're not documented*?

You really think those who don't know how POV-Ray works wil create better 
documentation than those who do know it?

> It's not like the developers & other people helping with POV-Ray would be 
> paid anything for it; our only payment is the joy of doing it (and every 
> programmer knows that implementation work is more fun than writing 
> documentation), the joy of seeing people get good results of it, and the 
> joy of receiving some motivating feedback from the community now and then.

I've been writing (and giving away) code since the eighties, I understand 
that joy. But I also understand that the chance of "seeing people get good 
results of it, and the joy of receiving some motivating feedback from the 
community" increases when people actually have chance to use my creations --  
which requires clear, unambiguous documentation. In which someone can find 
what they're looking for.

Otherwise you've created a magic binary that people *cannot* get good 
results from.

I understand well, that in the end you're just hurting yourself by not 
taking the opportunity to take every post to these ng as an opportunity to 
ask "how should we have written the answer to this in the docs and where did 
you look for it". But exactly *because* I've written my share of software, 
it frustrates me to no end that there's something here that seems pretty 
solid enough and appears to be getting better every time I look -- but it 
will never be something I use in any serious way, because nobody who knows 
the inner workings can be bothered to write down what is actually going on 
in this piece of code.

> No. To the programmer, the /intention/ is the end-all and be-all. If the 
> code fails to match that, it is buggy. If the documentation fails to match 
> that, it is either wrong (making an explicit statement that is not true), 
> incomplete (failing to make an explicit statement that is true bot not 
> necessarily obvious to the user), or imprecise (making a statement that 
> can be interpreted in a way that is true, but also in another way that is 
> not).

It's all fine that you have all these fine levels of gradation in which 
documentation fails. To the end-user, however, they make no difference: As 
Feynman said "if it disagrees with experiment, it's wrong".

But OK: so the documentation is "incomplete". Yet nobody is changing it. 
Instead *I* have been asked to improve on it - even though I have no idea of 
the very things that made me post here in the first place. It would be great 
if every post to these ng was taken as an opportunity to improve your 
stuff -- but if you don't want to do that, then why bother in the first 
place? Why even have these ng?

Once you posted the order in which the intersection test and clipping 
happen, that side of POV-Ray's behaviour was clear to me. So why haven't you 
put that explanation into the docs yet? Yes, I could try to do it myself, 
but I'd only mess it up in some subtle way since I only heard of it the 
first time yesterday (or whenever I read your reply).

> BTW, to the end user, the /expectation/ is the end-all and be-all; the 
> documentation can only serve to modify those expectations. So if some docs 
> do not explicitly mention the program's behaviour in a very rare 
> situation, who is outright /wrong/: The documentation, or the user's 
> expectations? I dare say the latter, because the docs simply cannot 
> foresee all that a user may expect.
>
> Also note that in real life there is no such thing as a /complete/ 
> documentation.

Actually, there is: the program as shipped is the final documentation. If 
you aren't sure about something, feed it to the program and see what 
happens. Whatever that is, that's how this program works.

Much of that can be predicted if you know the source, some details may hinge 
on details in some library or the compiler or OS. If someone says "just add 
all_intersections" and I add all_intersections and the result is a 
parse-error, then the advice was wrong. You may niggle over "incomplete" or 
"imprecise" or whatever, but when everything is said and done, following the 
advice to the dot leads to a parse error. *correct* advice solves my 
problem. *good* advice is like much of what you've been doing: pointing out 
what's wrong and where and how.

[...]
>> If that is "as intended", then this intention needs to be communicated 
>> (in
>> the docs, not here).
>
> (4) There is no /need/ to communicate the programmers' intentions to the 
> users. It's probably /helpful/, but there is no such /obligation/ to the 
> dev team - neither legally (see the license) nor morally (what you get 
> from the dev team is a free gift, and you can either take it or leave it, 
> and there's nothing you can /demand/ on top).

The concept of "need" is always tied to a purpose of some sort: in order to 
achieve X you *need* to Y.

If, to the programmers, the intent is the end-all be-all (as you claimed, 
and as I'm happy agreeing with) and if the programmers hope that people will 
get good use out of their producs (as you maintain and as I have no quarrels 
agreeing with) then they *need* to document their intent.

You are the only one here construing any kind of legal or moral dimension to 
the term "need".

Post a reply to this message

"SGeier" <som### [at] somewherecom> wrote:
> Here's what section 3.4.4 of the documentation shipping with the windows
> verion *actually* says:
> isosurface {
>   function { FUNCTION_ITEMS }
>   [contained_by { SPHERE | BOX }]
>   [threshold FLOAT_VALUE]
>   [accuracy FLOAT_VALUE]
>   [max_gradient FLOAT_VALUE]
>   [evaluate P0, P1, P2]
>   [open]
>   [max_trace INTEGER] | [all_intersections]
>   [OBJECT_MODIFIERS...]
>   }
> This tells me that a number of items can occur inside the isosurface{}
> entity. For example [threshold ...] or [contained_by ...] and a whole class
> of [object modifiers]. Nowhere in the docs is any mention that their order
> matters in any way and as a matter of fact some of the examples in the
> tutorial have them in an order different from the above.

Actually, you misread the grammar: As there is no "|" between the
isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
clearly states that putting "all_intersections" after "[OBJECT_MODIFIERS...]" is
not possible.

BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/  ;-)

    Thorsten

Post a reply to this message

"clipka" <ano### [at] anonymousorg> schreef in bericht 
news:4dd5a5ed$1@news.povray.org...
> all_intersections needs to go before the clipped_by statement. That, by 
> the way, is in the docs, too.

In all fairness, and without wanting to further the debate, this is neither
in the docs, nor in the tutorials. Well, at least I did not find it. Neither
is clipped_by mentioned by the way, in the isosurface section, so the error
seems very comprehensible to me.

The logical stream of thought probably is that contained_by and clipped_by
are equivalent (which they are not?) and as contained_by is mentioned before
all_intersection in the docs....

No need to hone the sabers now  ;-)

Thomas

Post a reply to this message

[after reading Thorten's message above]
... and which shows, there is a semantic problem, difficult to solve in 
fact. Increased by the number of non-native speakers among us.. I have the 
impression that many people (me included) not always realise that Object 
Modifiers is much more than just transformations. :-)  The contained_by in 
isosurfaces is also an object modifier, strictly speaking.

I think that in this case, there should be a little sentence in the docs 
just stressing that all isosurface parameters have to be placed *before* 
any object modifier.

I hope this helps....

Thomas

Post a reply to this message

On 05/20/2011 04:46 AM, Thomas de Groot wrote:
> [after reading Thorten's message above]
> ... and which shows, there is a semantic problem, difficult to solve in
> fact. Increased by the number of non-native speakers among us.. I have the
> impression that many people (me included) not always realise that Object
> Modifiers is much more than just transformations. :-)  The contained_by in
> isosurfaces is also an object modifier, strictly speaking.
>
> I think that in this case, there should be a little sentence in the docs
> just stressing that all isosurface parameters have to be placed *before*
> any object modifier.
>
> I hope this helps....
>
> Thomas
>
>
ah ... finally something of substance! (instead of all this childish 
posturing) I added a "Note" just after the syntax diagram:

http://wiki.povray.org/content/Documentation:Reference_Section_4.2#Isosurface_Object

oh and btw the clue that clipped_by is indeed an object modifier is in 
the first sentence:

http://wiki.povray.org/content/Documentation:Reference_Section_4.5#Clipped_By

Post a reply to this message

"Thorsten Froehlich" <nomail@nomail> wrote:
> "SGeier" <som### [at] somewherecom> wrote:
> > Here's what section 3.4.4 of the documentation shipping with the windows
> > verion *actually* says:
> > isosurface {
> >   function { FUNCTION_ITEMS }
> >   [contained_by { SPHERE | BOX }]
> >   [threshold FLOAT_VALUE]
> >   [accuracy FLOAT_VALUE]
> >   [max_gradient FLOAT_VALUE]
> >   [evaluate P0, P1, P2]
> >   [open]
> >   [max_trace INTEGER] | [all_intersections]
> >   [OBJECT_MODIFIERS...]
> >   }
> > This tells me that a number of items can occur inside the isosurface{}
> > entity. For example [threshold ...] or [contained_by ...] and a whole class
> > of [object modifiers]. Nowhere in the docs is any mention that their order
> > matters in any way and as a matter of fact some of the examples in the
> > tutorial have them in an order different from the above.
>
> Actually, you misread the grammar: As there is no "|" between the
> isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
> clearly states that putting "all_intersections" after "[OBJECT_MODIFIERS...]" is
> not possible.
>
> BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/  ;-)
>
>     Thorsten


I just tried max_gradient before threshold. The scene did not bomb out in the
way that putting all_intersections in the wrong place does. His point is valid.

Post a reply to this message

On 20.05.11 09:46, Thomas de Groot wrote:
> [after reading Thorten's message above]
> ... and which shows, there is a semantic problem, difficult to solve in
> fact. Increased by the number of non-native speakers among us.. I have the
> impression that many people (me included) not always realise that Object
> Modifiers is much more than just transformations. :-)  The contained_by in
> isosurfaces is also an object modifier, strictly speaking.
>
> I think that in this case, there should be a little sentence in the docs
> just stressing that all isosurface parameters have to be placed *before*
> any object modifier.

Actually, this rule applies to many object modifiers in other objects as 
well. It is not a unique behavior in isosurfaces. And it is documented.

	Thorsten

Post a reply to this message

On 20.05.11 13:06, gregjohn wrote:
> "Thorsten Froehlich"<nomail@nomail>  wrote:
>> "SGeier"<som### [at] somewherecom>  wrote:
>>> Here's what section 3.4.4 of the documentation shipping with the windows
>>> verion *actually* says:
>>> isosurface {
>>>    function { FUNCTION_ITEMS }
>>>    [contained_by { SPHERE | BOX }]
>>>    [threshold FLOAT_VALUE]
>>>    [accuracy FLOAT_VALUE]
>>>    [max_gradient FLOAT_VALUE]
>>>    [evaluate P0, P1, P2]
>>>    [open]
>>>    [max_trace INTEGER] | [all_intersections]
>>>    [OBJECT_MODIFIERS...]
>>>    }
>>> This tells me that a number of items can occur inside the isosurface{}
>>> entity. For example [threshold ...] or [contained_by ...] and a whole class
>>> of [object modifiers]. Nowhere in the docs is any mention that their order
>>> matters in any way and as a matter of fact some of the examples in the
>>> tutorial have them in an order different from the above.
>>
>> Actually, you misread the grammar: As there is no "|" between the
>> isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
>> clearly states that putting "all_intersections" after "[OBJECT_MODIFIERS...]" is
>> not possible.
>>
>> BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/  ;-)
>>
>>      Thorsten
>
>
> I just tried max_gradient before threshold. The scene did not bomb out in the
> way that putting all_intersections in the wrong place does. His point is valid.

Your logic is broken - saying that the negation of my statement yields no 
error is not the same as what I said. Sorry.

	Thorsten

Post a reply to this message

On 20.05.11 12:14, Jim Holsenback wrote:
> ah ... finally something of substance! (instead of all this childish
> posturing) I added a "Note" just after the syntax diagram:
>
> http://wiki.povray.org/content/Documentation:Reference_Section_4.2#Isosurface_Object

Jim, please remove the note as it is superfluous and does not document 
anything special in isosurfaces that does not exist in other objects as 
well. The better place to improve is the grammar explanation section (the 
equivalent of http://www.povray.org/documentation/view/3.6.1/214/ ). It is 
not all that obvious for non-programmers and very brief.

> oh and btw the clue that clipped_by is indeed an object modifier is in the
> first sentence:
>
> http://wiki.povray.org/content/Documentation:Reference_Section_4.5#Clipped_By

I would say this is more than a hint - after all, it is a subsection of the 
"object modifiers" section :-)

	Thorsten

Post a reply to this message

"Thorsten Froehlich" <tho### [at] trfde> schreef in bericht 
news:4dd64fc9@news.povray.org...
> Actually, this rule applies to many object modifiers in other objects as 
> well. It is not a unique behavior in isosurfaces. And it is documented.

You are certainly right, but as it does not *always* apply, an extra note is 
not superfluous here and there. Never take for granted that everything is 
obvious for the layman ;-)

As I implied before, it is often a matter of semantics, and we try to tend 
towards perfection, which is impossible... but we try, we try!

Thomas

Post a reply to this message

"Jim Holsenback" <jho### [at] povrayorg> schreef in bericht 
news:4dd63f14$1@news.povray.org...
> ah ... finally something of substance! (instead of all this childish 
> posturing)

<grin>

> I added a "Note" just after the syntax diagram:
>
> http://wiki.povray.org/content/Documentation:Reference_Section_4.2#Isosurface_Object
>
> oh and btw the clue that clipped_by is indeed an object modifier is in the 
> first sentence:
>
> http://wiki.povray.org/content/Documentation:Reference_Section_4.5#Clipped_By

Yes, no doubt about that. It is mainly the fact that you have to be careful 
where to place those object modifiers which can be a problem (or not) as it 
doesn't always generate a parse error, and sometimes it might just generate 
unexpected results I guess.

Poll (not serious): Who knows all the docs content (and their cross-links) 
by heart?

Thomas

Post a reply to this message

Am 20.05.2011 03:56, schrieb SGeier:

>> If you think the documentation is bad, then you're happily invited to help
>> make it better.
>
> I am honestly not being facetious when I (honestly, serious!) ask: How is
> that supposed to work, when I don't know how POV-Ray works? I look into the
> documentation when something doesn't work as I expect. I learn something,
> try something, and realize it doesn't work as written in the docs either.
> How on earth am I supposed to now suddenly write better docs?
>
> I've been poking my head into POV-Ray for several years now - I d/l the
> current version, I tinker with it, I give up. Because every time I run into
> the same kinds of problems that aren't documented and when I ask about them
> nobody takes the time to examine what was communicated how in the docs and
> when I complain about the docs I'm being told that I'm free to make them
> better. But how should I do that, when I don't even understand some very
> basic, simple things about POV-Ray *because they're not documented*?

You're surprised, you ask, you learn, you document what you learned so 
that others don't need to ask again. That's how it /could/ work.

The dev team is not constantly skimming through the docs with the eyes 
of a new user (how could they!) searching for stuff that's poorly 
documented.

Nor does the dev team have an abundance of energy to work on the docs. 
Jim is doing a great work on that, but he has a life, too. Essentially 
we need people who not only /find/ flaws in the docs, but also /fix/ them.

Another thing that should be noted is that the dev team has changed a 
lot over the lifetime of POV-Ray so far; some members left, others went, 
and various people outside the official dev team contributed code and/or 
documentation. There are things in both the docs and the code the 
current dev team does /not/ know by heart.

> You really think those who don't know how POV-Ray works wil create better
> documentation than those who do know it?

That may well be. Software authors who know how their software works 
tend to take some things for granted that new users possibly won't. 
They're also prone to language that a fellow programmer might 
understand, but an artistically oriented user may possibly not.

> I've been writing (and giving away) code since the eighties, I understand
> that joy. But I also understand that the chance of "seeing people get good
> results of it, and the joy of receiving some motivating feedback from the
> community" increases when people actually have chance to use my creations --
> which requires clear, unambiguous documentation. In which someone can find
> what they're looking for.

... and I bet you've always supplied a correct, error-free, complete and 
end-user-friendly documentation, huh?

If you did, then congrats - you might be the type of person we could 
need help from.

> Otherwise you've created a magic binary that people *cannot* get good
> results from.

Well, the source code is there to have a look at, too (and even toy 
around with). It's the most precise documentation we cold ever ask for. 
(Unfortunately it's not very end-user-palatable.)

> But exactly *because* I've written my share of software,
> it frustrates me to no end that there's something here that seems pretty
> solid enough and appears to be getting better every time I look -- but it
> will never be something I use in any serious way, because nobody who knows
> the inner workings can be bothered to write down what is actually going on
> in this piece of code.

You know, I have my own approach at things that frustrate me.

A while ago it frustrated me as a POV-Ray end user that while POV-Ray 
3.7 beta (I think it was beta 28 or 29) could make use of multiple 
cores, it couldn't do so for radiosity.

Knowing that the dev team was pretty busy, I decided to give it a try 
and invest some of my /own/ energy into /making/ it use multiple cores 
for radiosity.

I did. Previously I had only vague ideas of how POV-Ray worked at its 
core, how radiosity worked, and so forth. I invested the energy to 
/learn/ how it worked, in order to fix what was frustrating me. Yes, I 
did my own share of ranting over the existing radiosity code as I dug 
deeper into it - but at the same time I busied myself fixing it.

So pointing out flaws is one thing - ranting about them without adding 
anything more helpful is a different thing.

> It's all fine that you have all these fine levels of gradation in which
> documentation fails. To the end-user, however, they make no difference: As
> Feynman said "if it disagrees with experiment, it's wrong".
>
> But OK: so the documentation is "incomplete". Yet nobody is changing it.
> Instead *I* have been asked to improve on it - even though I have no idea of
> the very things that made me post here in the first place. It would be great
> if every post to these ng was taken as an opportunity to improve your
> stuff -- but if you don't want to do that, then why bother in the first
> place? Why even have these ng?

Believe me - we /want/ the documentation improved. We just don't have 
the energy ourselves at present. There's other things that have priority 
(for us as a dev team) over fixing stuff in the docs that hasn't changed 
at all from 3.6 to 3.7.

> Once you posted the order in which the intersection test and clipping
> happen, that side of POV-Ray's behaviour was clear to me. So why haven't you
> put that explanation into the docs yet? Yes, I could try to do it myself,
> but I'd only mess it up in some subtle way since I only heard of it the
> first time yesterday (or whenever I read your reply).

I'm not doing it myself because I'm poor at writing end-user docs; being 
pedantic as I am, I find it difficult to find a proper balance between 
precision and legibility, so it costs me a lot of energy to do such doc 
changes. I have a much easier time explaining things to individual 
people than to a broad anonymous audience. And if we'd be talking about 
a technical specification, where precision is all that matters, I'd have 
a much easier time.

> Much of that can be predicted if you know the source, some details may hinge
> on details in some library or the compiler or OS. If someone says "just add
> all_intersections" and I add all_intersections and the result is a
> parse-error, then the advice was wrong. You may niggle over "incomplete" or
> "imprecise" or whatever, but when everything is said and done, following the
> advice to the dot leads to a parse error. *correct* advice solves my
> problem. *good* advice is like much of what you've been doing: pointing out
> what's wrong and where and how.

So Thorsten's advice was "incorrect" because he simply wrote "just add 
all_intersections" rather than "just add all_intersections where it fits 
according to the documented isosurface syntax"? Great. I prefer to disagree.

Post a reply to this message

Am 20.05.2011 03:12, schrieb SGeier:

>> Otherwise you'd have noticed that above code does not support your point
>> at all, but instead just gives a parse error.
>
> Indeed, it does. Which I noticed. Which is why I was trying to coax Thorsten
> Froehlich into trying his own suggestion. Which was this:
>
>> add all_intersections and just be happy.
>
> Which does not work. Thank you for trying it. Thank you for noticing that
> *the advice given by people who know the program so well DOES NOT WORK*.
>
>> all_intersections needs to go before the clipped_by statement.
>
> Thank you for pointing that out. Always pleased to learn something.
>
>> That, by the way, is in the docs, too.
>
> No, it is not.

Yes, it is.

> This is exactly where our views on the documentation differ drastically.
> Yes, now that you mention it, I can see how one *could* read the
> documentation such as to suggest that. However it *definitely* does not
> contain the sentence
>
> "all_intersections needs to go before the clipped_by statement."
>
> or any sentence anywhere close to it.

It does explicitly specify it in the section you quoted:

> Here's what section 3.4.4 of the documentation shipping with the windows
> verion *actually* says:
> isosurface {
>    function { FUNCTION_ITEMS }
>    [contained_by { SPHERE | BOX }]
>    [threshold FLOAT_VALUE]
>    [accuracy FLOAT_VALUE]
>    [max_gradient FLOAT_VALUE]
>    [evaluate P0, P1, P2]
>    [open]
>    [max_trace INTEGER] | [all_intersections]
>    [OBJECT_MODIFIERS...]
>    }
> This tells me that a number of items can occur inside the isosurface{}
> entity. For example [threshold ...] or [contained_by ...] and a whole class
> of [object modifiers]. Nowhere in the docs is any mention that their order
> matters in any way and as a matter of fact some of the examples in the
> tutorial have them in an order different from the above.

Read section 3.1.1 "Notation and Basic Assumptions"; nowhere in there 
does it say that the items can be specified in arbitrary order, so it's 
your assumption that is wrong again here. The fact that /some/ of the 
stuff can be re-ordered is, as a matter of fact, a feature documented 
elsewhere.

See sections 3.8 "Quick Reference" for a description of the notation 
used for the syntax specification, and section 3.8.8.4 "Isosurface" for 
the description of the isosurface syntax. There you will find that 
ISOSURFACE_ITEMS (including all_intersections) may be specified in 
arbitrary order, but must go before OBJECT_MODIFIERS.

> And when someone like myself complains about the documentation we're being
> told that we should improve it. But of course we *cannot* improve it since
> there is no way to find out what the real behaviour actually *is*, since the
> documentation doesn't mention it and asking on usenet gets me helpful advice
> like

(As you seem to like precision, please note that we're not on usenet; 
we're on a private news server.)

>> add all_intersections and just be happy.
>
> which I had seen, tried, and noticed it didn't work. So I figured that
> something changed since the docs were written, so I post here.
>
> So it turns out the whole thing was *really* not about clipping at all, all
> the blah-blah about reading the documentation on clipping and max_trace and
> all_intersections was completely besides the point. Apparently neither you
> nor Thorsten had the slightest idea what was wrong, you just immediately
> assumed that *obviously* I hadn't read the documentation and *obviously* you
> know exactly what's going on, no need to actually investigate anything or
> think about anything.

Thorsten knew /exactly/ why the stuff was happening that you saw, and I 
myself didn't post a reply until I had figured it out as well. (Believe 
me, while as a matter of fact I often /do/ start writing responses to 
reports of possible errors before checking it out, I virtually never 
press "send" before I checked that I'm not talking nonsense.) The only 
thing unclear was why you insisted it was an error.

> Now why is it like pulling teeth to get someone to actually come out and
> examine things and state these things here on the ng?

Maybe because with your originally posted code we didn't need to examine 
things, because your description matched the behaviour /we/ did expect?

> Until I posted the few
> lines there in toto, nobody around here had even *tried* to diagnose what my
> problem might be -- you all just assumed you knew exactly what the problem
> was (and it turned out to be somewhere else).

That was when your problem apparently shifted, from getting an 
unexpected (for you) result from your originally posted code to some 
rather vague complaint in connection with all_intersections (which you 
hadn't mentioned earlier, so we all naturally assumed - and still assume 
- you hadn't tried it).

So why are you surprised you're getting a more thorough inspection only 
later? It's like you're phoning up the garage complaining to the 
mechanic that the engine on your car stutters, and by the way there's a 
red light in the display, looking somewhat like a fuel pump (*); not 
surprisingly the mechanic will simply recommend to try and fill her up 
(knowing that stuttering engines are to be expected when there's a lack 
of fuel), but now you start complaining that the fuel pump doesn't fit 
in the tank. It's probably only /then/ that the mechanic will consider a 
more thorough inspection. (And as it turns out the problem is that you 
tried to pump your diesel at a pump for heavy trucks, so you blame the 
car manufacturer for failing to make a note of this incompatibility in 
the car's user manual.)

(* I am well aware that the example limps here because usually those 
lights are well documented. However, the fact that a car needs fuel to 
drive is typically taken for granted.)

>> You're complaining that Thorsten did not try out the code you posted - but
>> why should he, if he knows POV-Ray good enough (and yes, obviously better
>> than you) that he's not in the least surprised, and can even tell you
>> /why/ it is happening? (Besides, what makes you so sure that he didn't try
>> it?)
>
> Because his answer "add this line to your SDL and it'll all work" did NOT
> work. Either he doesn't know POV-Ray as well as you both think, or he knows
> it *too* well, where he's not stating what assumptions *he* is making (which
> is exactly what I find myself accused of).

... or he knows some things mentioned in sections of the docs you didn't 
read.

Post a reply to this message

Am 20.05.2011 09:46, schrieb Thomas de Groot:

> The contained_by in
> isosurfaces is also an object modifier, strictly speaking.

No, not really. Not according to how OBJECT_MODIFIERS is defined 
syntactically.

> I think that in this case, there should be a little sentence in the docs
> just stressing that all isosurface parameters have to be placed *before*
> any object modifier.

Note the same goes for /any/ object type: Object-type specific keywords 
must go first, before any generic object modifiers. So do we need such a 
sentence in the description of /all/ the primitives?

Post a reply to this message

Am 20.05.2011 13:39, schrieb Thorsten Froehlich:
> On 20.05.11 12:14, Jim Holsenback wrote:
>> ah ... finally something of substance! (instead of all this childish
>> posturing) I added a "Note" just after the syntax diagram:
>>
>>
http://wiki.povray.org/content/Documentation:Reference_Section_4.2#Isosurface_Object
>>
>
> Jim, please remove the note as it is superfluous and does not document
> anything special in isosurfaces that does not exist in other objects as
> well. The better place to improve is the grammar explanation section
> (the equivalent of http://www.povray.org/documentation/view/3.6.1/214/
> ). It is not all that obvious for non-programmers and very brief.

Maybe it would be good to use the same notation as in the quick 
reference, using "&" to list items with arbitrary ordering.

Post a reply to this message

On 20.05.11 14:51, clipka wrote:
> Am 20.05.2011 13:39, schrieb Thorsten Froehlich:
>> On 20.05.11 12:14, Jim Holsenback wrote:
>>> ah ... finally something of substance! (instead of all this childish
>>> posturing) I added a "Note" just after the syntax diagram:
>>>
>>>
http://wiki.povray.org/content/Documentation:Reference_Section_4.2#Isosurface_Object
 >>
>> Jim, please remove the note as it is superfluous and does not document
>> anything special in isosurfaces that does not exist in other objects as
>> well. The better place to improve is the grammar explanation section
>> (the equivalent of http://www.povray.org/documentation/view/3.6.1/214/
>> ). It is not all that obvious for non-programmers and very brief.
>
> Maybe it would be good to use the same notation as in the quick reference,
> using "&" to list items with arbitrary ordering.

I think aligning the quick ref and the remainder of the documentation would 
be a good idea. It is a lot of tedious editing required though :-(

	Thorsten

Post a reply to this message

"clipka" <ano### [at] anonymousorg> schreef in bericht 
news:4dd66333$1@news.povray.org...
> Am 20.05.2011 09:46, schrieb Thomas de Groot:
>
>> The contained_by in
>> isosurfaces is also an object modifier, strictly speaking.
>
> No, not really. Not according to how OBJECT_MODIFIERS is defined 
> syntactically.

I am sure I agree with you here. What I mean to say is that - for the 
layman - contained_by is looked upon in the same way as an object modifier.

> Note the same goes for /any/ object type: Object-type specific keywords 
> must go first, before any generic object modifiers. So do we need such a 
> sentence in the description of /all/ the primitives?

Well, it seems I am not one of those lucky ones who know the docs perfectly 
:-)  Your point is well taken, only I had never really thought about it in 
that way, and I suppose many are in the same position as me...

I think this whole discussion is not useless. We all learned something 
essential it seems. Hurray!  :-)

Thomas

Post a reply to this message

Have the clocks gone back 10 years?
Have we returned to the days where the simplest question was met by RTFM?

I thought that we had developed into a nice community not one that 
answered a legitimate question with “I know and I’m not going to tell you”.

I’m very disappointed with the behaviour of some people here.

Post a reply to this message

On 21/05/2011 23:15, Stephen wrote:
> Have the clocks gone back 10 years?
> Have we returned to the days where the simplest question was met by RTFM?
> 
> I thought that we had developed into a nice community not one that 
> answered a legitimate question with “I know and I’m not going to tell you”.
> 
> I’m very disappointed with the behaviour of some people here.

I'd like to suggest that the response of some people in this group could
have been a bit nicer. Please however understand that geeks are sometimes a
little short on social graces :(

Post a reply to this message

On 21/05/2011 2:40 PM, Chris Cason wrote:
> I'd like to suggest that the response of some people in this group could
> have been a bit nicer.

And more helpful IMO.

> Please however understand that geeks are sometimes a
> little short on social graces:(

And that is an acceptable excuse?
It is like saying that we Glaswegians are renowned for mindless violence 
so don't take the stitches and broken leg personally.

An apology goes a long way. (Not directed at you cobber.)

-- 
Regards
     Stephen

Post a reply to this message

Stephen <mcavoys_at@aoldotcom> wrote:
> Have the clocks gone back 10 years?
> Have we returned to the days where the simplest question was met by RTFM?

> I thought that we had developed into a nice community not one that 
> answered a legitimate question with ???I know and I???m not going to tell you???.

> I???m very disappointed with the behaviour of some people here.

  I don't think it's fair to judge the entire community because of the
behavior of one person. People are different and have different
personalities, and sometimes personalities might clash a bit. However,
judging everybody for this is not nice.

-- 
                                                          - Warp

Post a reply to this message

On 21/05/2011 7:56 PM, Warp wrote:
>    I don't think it's fair to judge the entire community because of the
> behavior of one person. People are different and have different
> personalities, and sometimes personalities might clash a bit. However,
> judging everybody for this is not nice.

You are entirely right.
With all that implies.

-- 
Regards
     Stephen

Post a reply to this message

"Thorsten Froehlich" <nomail@nomail> wrote in message 
news:web.4dd613da955938cce619b42c0@news.povray.org...
> Actually, you misread the grammar: As there is no "|" between the
> isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
> clearly states that putting "all_intersections" after 
> "[OBJECT_MODIFIERS...]" is
> not possible.
>
> BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/ 
> ;-)
>
>    Thorsten
>


Is this some kind of character set issue? Did you really mean to use a pipe 
symbol (vertical bar) in your quotation marks up there?

I'm staring at the page to which you posted a link there and I fail to see 
ANY mention of any relationship between a pipe symbol and the order in which 
things need to be provided. As a matter of fact the only mention of a pipe 
symbol that I see there is this pair of sentences:

> Choices are represented by a vertical bar between
> syntax items. For example a choice between three
> items would be written as ITEM1 | ITEM2 | ITEM3.

Could you please quote to me the sentence/s on that page that you linked up 
there that indicates that vertical bars have anything whatsoever to do with 
the order of things.

(Yes, I'm aware that the quick-reference has such a statement, but it also 
has a warning that the syntax convention there is different from the user 
documentation).

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4dd66204@news.povray.org...
> Am 20.05.2011 03:12, schrieb SGeier:
>> Here's what section 3.4.4 of the documentation shipping with the windows
>> verion *actually* says:
>> isosurface {
>>    function { FUNCTION_ITEMS }
>>    [contained_by { SPHERE | BOX }]
>>    [threshold FLOAT_VALUE]
>>    [accuracy FLOAT_VALUE]
>>    [max_gradient FLOAT_VALUE]
>>    [evaluate P0, P1, P2]
>>    [open]
>>    [max_trace INTEGER] | [all_intersections]
>>    [OBJECT_MODIFIERS...]
>>    }
>> This tells me that a number of items can occur inside the isosurface{}
>> entity. For example [threshold ...] or [contained_by ...] and a whole 
>> class
>> of [object modifiers]. Nowhere in the docs is any mention that their 
>> order
>> matters in any way and as a matter of fact some of the examples in the
>> tutorial have them in an order different from the above.
>
> Read section 3.1.1 "Notation and Basic Assumptions"; nowhere in there does 
> it say that the items can be specified in arbitrary order, so it's your 
> assumption that is wrong again here.

No, it is not an assumption. It is an *observation*.

I learned about isosurfaces by reading the isosurface tutorial. Isn't that 
what it's for? In the tutorial there are bits of example code. They have 
various items in various order, including order that is expressly in 
conflict with the above list. For example section 2.3.3.3.6 of the 
documentation that ships with the current RC3 has this piece of code:

  #declare Blob_threshold=0.01;

  isosurface {
    function {
      (1+Blob_threshold)
      -pow(Blob_threshold, fn_A(x,y,z))
      -pow(Blob_threshold, fn_B(x,y,z))
    }
    max_gradient 4
    contained_by { box { -2, 2 } }
  }


This has max_gradient *before* contained_by. And it works just fine. At this 
point I'm not exactly "assuming" anything when I start moving the other 
parts around -- and meeting with perfectly fine success. No problems placing 
any of the above in any order - *except* those "object_modifiers".

And no, nowhere in the tutorial is there any mention that there's any 
exceptions to this floating around.

>
> See sections 3.8 "Quick Reference" for a description of the notation used 
> for the syntax specification, and section 3.8.8.4 "Isosurface" for the 
> description of the isosurface syntax.

I'm having trouble figuring out how things work by reading the verbose parts 
of the documentation and you think I'm going to go to the *quick-reference* 
to look them up? Seriously?

Especially after I've seen it start with a warning that it uses incompatible 
notation and thus that anything I learn here will not actually transfer to 
what I read elsewhere in the docs?

> [...] The only thing unclear was why you insisted it was an error.

I didn't "insist" on anything - Here's the first and last part of my 
original post:



>"SGeier" <som### [at] somewherecom> wrote in message 
>news:<4dd316e8$1@news.povray.org>...

> OK, I'm either doing something phenomenally stupid, or there's a blatant 
> bug

> in isosurface{} in 3.7rc3.

>

> Step 1) Consider the following simple scene:

[...]

> But in step 4, the back/inside of the isosurface is gone.

>

> Why?

>



I posted something and asked "why is this like that". If someone had simply 
told me why it is that way, I would have learned something. Instead I was 
told "you didn't read the docs".  Huh. Very helpful. Turns out what I was 
*really* bumping into was about some subtle distinction about the items I 
can put into an isosurface{} statement, namely that some of them are 
"object_modifiers" and assume a special place, while others are 
object-specific and can go wherever.

Why? Who knows. I already have a max_trace_level in my global_settings, but 
isosurface ignores that and instead needs to be told its own specialized 
max_trace and when I do that it magically becomes  isosurface-specific and 
thus cannot be placed after clipped_by. Even though it is only ever needed 
*because* I am using clipped_by in the first place. IF I use clipped_by, 
THEN I need a max_trace and it must come BEFORE the clipped_by that 
necessitated it. And this is so amazingly *obvious* that it is sufficient to 
post "you didn't read the docs" because the docs are so completely clear on 
this.

Seriously.

Yes, I was making an assumption there somewhere: if the program and the docs 
disagree, the program wins. Thus something changed in the program since the 
docs were written. Not a big deal - let me post and ask around. Hah.

>
> ... or he knows some things mentioned in sections of the docs you didn't 
> read.

To be as clear as I can: I have certainly NOT read every single page in the 
docs. Because the documentation is amazingly self-indulgent in page upon 
page of tutorials on what the frickin' #if command does, but fails to 
mention the basic things someone trying to compose scripts in the SD 
language actually needs to know. Except for the few that are actually tucked 
away somewhere and sometimes I even sumble across them (usually while trying 
to figure out something else).

I have *easily* spent five times as much time reading POV-Ray documentation 
than reading Python docs; yet I am completely confident when I write Python 
code because what I have read explained the *why* of the various things in 
the simple, straightforward order in which an intelligent reader would 
expect to read them. While I keep flailing around in POV-Ray because such 
simple things as the order of ray-intersection test and clipping are either 
not documented at all or if they are then they're buried somewhere.

Post a reply to this message

Le 2011/05/23 21:21, SGeier a écrit :
> "clipka"<ano### [at] anonymousorg>  wrote in message
> news:4dd66204@news.povray.org...
>> Am 20.05.2011 03:12, schrieb SGeier:
>>> Here's what section 3.4.4 of the documentation shipping with the windows
>>> verion *actually* says:
>>> isosurface {
>>>     function { FUNCTION_ITEMS }
>>>     [contained_by { SPHERE | BOX }]
>>>     [threshold FLOAT_VALUE]
>>>     [accuracy FLOAT_VALUE]
>>>     [max_gradient FLOAT_VALUE]
>>>     [evaluate P0, P1, P2]
>>>     [open]
>>>     [max_trace INTEGER] | [all_intersections]
ALL items between the function and here can be placed in ANY order. They 
are objects items and are often specific to the primitive used.
>>>     [OBJECT_MODIFIERS...]
>>>     }

Note that all items are lower case, then, you have OBJECT_MODIFIERS in 
all UPPERCASE. This tells you that OBJECT_MODIFIERS is not in the same 
category. In fact, it tells that OBJECT_MODIFIERS in not an item.

>>> This tells me that a number of items can occur inside the isosurface{}
>>> entity. For example [threshold ...] or [contained_by ...] and a whole
>>> class
>>> of [object modifiers]. Nowhere in the docs is any mention that their
>>> order
>>> matters in any way and as a matter of fact some of the examples in the
>>> tutorial have them in an order different from the above.

The documentations clearly state that all object modifiers must follow 
all objects items.

>>
>> Read section 3.1.1 "Notation and Basic Assumptions"; nowhere in there does
>> it say that the items can be specified in arbitrary order, so it's your
>> assumption that is wrong again here.

You seems to confuse "items" and "modifiers".
Items can be in any order.
Modifiers also can be specified in about any order. They also MUST 
follow the last item.

>
> No, it is not an assumption. It is an *observation*.
>
> I learned about isosurfaces by reading the isosurface tutorial. Isn't that
> what it's for? In the tutorial there are bits of example code. They have
> various items in various order, including order that is expressly in
> conflict with the above list. For example section 2.3.3.3.6 of the
> documentation that ships with the current RC3 has this piece of code:
>
>    #declare Blob_threshold=0.01;
>
>    isosurface {
>      function {
>        (1+Blob_threshold)
>        -pow(Blob_threshold, fn_A(x,y,z))
>        -pow(Blob_threshold, fn_B(x,y,z))
>      }
>      max_gradient 4
>      contained_by { box { -2, 2 } }
>    }
>
>
> This has max_gradient *before* contained_by. And it works just fine. At this
> point I'm not exactly "assuming" anything when I start moving the other
> parts around -- and meeting with perfectly fine success. No problems placing
> any of the above in any order - *except* those "object_modifiers".

Still because OBJECT_MODIFIERS are NOT object items.

>
> And no, nowhere in the tutorial is there any mention that there's any
> exceptions to this floating around.

Uniquely because the tutorials don't scale, rotate or translate the 
sample isosurfaces...
The isosurface tutorial concentrate only on creating the isosurface, not 
modifying them, clipping them or using them in CSG with other primitives.

>
>>
>> See sections 3.8 "Quick Reference" for a description of the notation used
>> for the syntax specification, and section 3.8.8.4 "Isosurface" for the
>> description of the isosurface syntax.
>
> I'm having trouble figuring out how things work by reading the verbose parts
> of the documentation and you think I'm going to go to the *quick-reference*
> to look them up? Seriously?
>
> Especially after I've seen it start with a warning that it uses incompatible
> notation and thus that anything I learn here will not actually transfer to
> what I read elsewhere in the docs?
>
>> [...] The only thing unclear was why you insisted it was an error.
>
> I didn't "insist" on anything - Here's the first and last part of my
> original post:
>
>
>
>> "SGeier"<som### [at] somewherecom>  wrote in message
>> news:<4dd316e8$1@news.povray.org>...
>
>> OK, I'm either doing something phenomenally stupid, or there's a blatant
>> bug
>
>> in isosurface{} in 3.7rc3.
You asked if there was a bug, and there is none.
It leaves the "something phenomenally stupid" part...

>
>>
>
>> Step 1) Consider the following simple scene:
>
> [...]
>
>> But in step 4, the back/inside of the isosurface is gone.
>
>>
>
>> Why?
>
>>
>
>
>
> I posted something and asked "why is this like that". If someone had simply
> told me why it is that way, I would have learned something. Instead I was
> told "you didn't read the docs".  Huh. Very helpful. Turns out what I was
> *really* bumping into was about some subtle distinction about the items I
> can put into an isosurface{} statement, namely that some of them are
> "object_modifiers" and assume a special place, while others are
> object-specific and can go wherever.

Again, "object_modifiers" are not items. It thus don't follows the 
general rule of order as the items.

>
> Why? Who knows. I already have a max_trace_level in my global_settings, but
> isosurface ignores that and instead needs to be told its own specialized
> max_trace and when I do that it magically becomes  isosurface-specific and
> thus cannot be placed after clipped_by. Even though it is only ever needed
> *because* I am using clipped_by in the first place. IF I use clipped_by,
> THEN I need a max_trace and it must come BEFORE the clipped_by that
> necessitated it. And this is so amazingly *obvious* that it is sufficient to
> post "you didn't read the docs" because the docs are so completely clear on
> this.
>
> Seriously.
>
> Yes, I was making an assumption there somewhere: if the program and the docs
> disagree, the program wins. Thus something changed in the program since the
> docs were written. Not a big deal - let me post and ask around. Hah.

Your assumption and interpretation <> documentations that are fidel to 
the programm.
This is that way at least since version 1.

primitive_name{mendatory_items [optional_items_in_any_order] 
[OBJECT_MODIFIERS_IN_ANY_ORDER]}

>
>>
>> ... or he knows some things mentioned in sections of the docs you didn't
>> read.
>
> To be as clear as I can: I have certainly NOT read every single page in the
> docs. Because the documentation is amazingly self-indulgent in page upon
> page of tutorials on what the frickin' #if command does, but fails to
> mention the basic things someone trying to compose scripts in the SD
> language actually needs to know. Except for the few that are actually tucked
> away somewhere and sometimes I even sumble across them (usually while trying
> to figure out something else).
>
> I have *easily* spent five times as much time reading POV-Ray documentation
> than reading Python docs; yet I am completely confident when I write Python
> code because what I have read explained the *why* of the various things in
> the simple, straightforward order in which an intelligent reader would
> expect to read them. While I keep flailing around in POV-Ray because such
> simple things as the order of ray-intersection test and clipping are either
> not documented at all or if they are then they're buried somewhere.
>
>

If you look around, you'll find that:
Most of the time, max_gradient immediately FOLLOWS the function. It's 
question of style and general concensus.
Also, most of the time, contained_by is the last isosurface parameter. 
Also a question of style and concensus.

max_trace_level apply exclusively to transparency and reflections, never 
ever to any surface that can never be visible. 
max_trace/all_intersections is very different and there is no "magic" 
transforming one into the other.
max_trace_level is a global setting that affect the evaluation of 
tracing rays.
max_trace is an object attribute specific to the isosurface in exactly 
the same way that max_gradient is. It affect how the isosurface is 
evaluated if there are surfaces that can't be seen. Please note that 
ther is NO "_level" here. They do LOOK similar, but are totaly different 
things.

Then, you have clipped_by, whitch is an OBJECT MODIFIER.

ALL object modifiers always MUST follow ANY object items. This also 
apply to any pigment, texture, material, translate, scale and rotate. 
You can't translate an isosurface before you use contained_by. Also, you 
can't apply a pigment before, say, accuracy or open.



Alain

Post a reply to this message

> I'm staring at the page to which you posted a link there and I fail to see 
> ANY mention of any relationship between a pipe symbol and the order in which 
> things need to be provided.

What that documentation page fails to mention explicitely is that,
in absence of special syntax, everything is to be taken literally
and in the order specified.

For example, "sphere {<Center>, Radius}" means first write sphere,
then write curcly brace open, then write vector expression, then write
scalar expression, then write closing brace.

The reference to the pipe is that typically elements A and B
that may be present in arbitrary order could be given as:

[SOME_ITEM...]

SOME_ITEM: A | B

However, such syntax allows you to give the same item multiple
times, even if that was not the intent. It also seems that some
SDL descriptions are given in a way that imply a specific parameter
order although that is not the intent and not the implementation.
This may lead to confusion where order is important.

For non-technical users this page might benefit from an example.

Post a reply to this message

"Christian Froeschlin" <chr### [at] chrfrde> wrote in message 
news:4ddb8acc@news.povray.org...
>> I'm staring at the page to which you posted a link there and I fail to 
>> see ANY mention of any relationship between a pipe symbol and the order 
>> in which things need to be provided.
>
> What that documentation page fails to mention explicitely is that,
> in absence of special syntax, everything is to be taken literally
> and in the order specified.

"Is to be taken" - by whos opinion? Who says that this is so? The 
programmers certainly don't say so. If you disagree with this statement, 
show me where they do. Oh, you just said that the documentation "fails to 
mention" that. Bummer.

The documentation also fails to mention that chocolate is evil and should be 
outlawed. Does that mean you, I or anybody can just claim that it is somehow 
"meant" even though it "isn't mentioned explicitely"?

The various items in isosurface *can* be used in arbitrary order, as 
*demonstrated* in the tutorial; even though there is no "special syntax" 
anywhere. *Except* for those "object_modifiers" that are no more nor less 
marked with pipe-symbols or anything but somehow can only go at the very 
end. The only vertical pipe is between [max_trace ...] and 
[all_intersections] indicating an either/or choice as vertical pipes do in 
all EBNF I've ever seen.

So not only does the page "fail to mention expressly" that order is 
important, if it did mention such a thing it would be *false* because the 
behaviour of the program itself is such that order does not matter *except* 
in the case of object modifiers that have to be at the end. And where I'm 
coming from, where the documentation and the behaviour of the program 
differ, the program is right and the documentation is wrong. Fortunately it 
is NOT wrong here, because it does not actually say such a thing.

Meanwhile, this was Thorsten Froehlich's claim:
>Actually, you misread the grammar: As there is no "|" between the
>isosurface-specific modifiers and the "[OBJECT_MODIFIERS...]", the grammar
>clearly states that putting "all_intersections" after 
>"[OBJECT_MODIFIERS...]" is
>not possible.

Cool, if "the gramma clearly states" such a thing then it should be easy to 
show me *where* the grammar clearly states such. Because I somehow missed it 
and so I'm assuming it is in some area of the documentation that I didn't 
read and I assume there's more things in that section that I need to know.

His further claim was

> BTW, that you find at http://www.povray.org/documentation/view/3.6.1/214/

which unfortunately does NOT show any such information at all, so I'm going 
to assume that he *accidently* pointed me to the wrong section in the 
documentation.

Post a reply to this message

Am 24.05.2011 03:21, schrieb SGeier:

>>> This tells me that a number of items can occur inside the isosurface{}
>>> entity. For example [threshold ...] or [contained_by ...] and a whole
>>> class
>>> of [object modifiers]. Nowhere in the docs is any mention that their
>>> order
>>> matters in any way and as a matter of fact some of the examples in the
>>> tutorial have them in an order different from the above.
>>
>> Read section 3.1.1 "Notation and Basic Assumptions"; nowhere in there does
>> it say that the items can be specified in arbitrary order, so it's your
>> assumption that is wrong again here.
>
> No, it is not an assumption. It is an *observation*.

It's an observation that /some/ items can be specified in arbitrary 
order (and as a matter of fact happens to be true for all 
non-OBJECT_MODIFIER items). However, it was only your /assumption/ that 
it was also true for /all/ items including OBJECT_MODIFIER elements.


That said, rather than continuing this interesting nitpicking contest, 
please take a step back, rethink, and tell us what you /want/ from the 
dev team.

No, we won't improve the docs much before the 3.70 repease proper 
(unless some volunteer(s) happen to step up to actively help us with 
them - and by actively I mean more than demonstrating that you didn't 
understand them), for the simple reason that there's lack of manpower in 
that respect. Yes, the docs badly do need some improvement, but (1) 
that's not a new issue caused by the 3.6 -> 3.7 transition, and (2) it's 
not realistically achievable with just adding a bit of more patchwork 
here and there; what's really necessary is a systematic overhaul, which 
will possibly include a major rewrite and/or restructuring of many sections.

Post a reply to this message

Am 25.05.2011 01:35, schrieb SGeier:

> And where I'm
> coming from, where the documentation and the behaviour of the program
> differ, the program is right and the documentation is wrong.

Where /I'm/ coming from, this is /not/ necessarily the case, but 
definitely depends on various other circumstances; for instance, where 
the program /tolerates/ something that's not explicitly in the docs, 
this is an undocumented feature, may be subject to change without 
notice, and therefore should still be avoided despite being tolerated.

Post a reply to this message

On 25/05/2011 12:51 AM, clipka wrote:
>
> That said, rather than continuing this interesting nitpicking contest,
> please take a step back, rethink, and tell us what you /want/ from the
> dev team.

Now that is sensible.
There is no need to make things worse than they re already are.

-- 
Regards
     Stephen

Post a reply to this message

On 05/24/2011 08:51 PM, clipka wrote:
> No, we won't improve the docs much before the 3.70 repease proper
> (unless some volunteer(s) happen to step up to actively help us with
> them - and by actively I mean more than demonstrating that you didn't
> understand them), for the simple reason that there's lack of manpower in
> that respect. Yes, the docs badly do need some improvement, but (1)
> that's not a new issue caused by the 3.6 -> 3.7 transition, and (2) it's
> not realistically achievable with just adding a bit of more patchwork
> here and there; what's really necessary is a systematic overhaul, which
> will possibly include a major rewrite and/or restructuring of many
> sections.

couldn't agree more with what you've said here ... I think my focus was 
to get stuff (new features) added in as they just weren't documented 
period, and also the code to pull it back out of the wiki in html form. 
I /did/ touch on some house keeping issues that were just plain in need 
of help, but I'm just one person, so for sure there are some areas that 
just didn't get touched. I /still/ give the docs pretty high marks, 
because hey I've seen MUCH worse (other apps) and would be the first to 
admit that there are areas that still need some attention ... everyone 
knows that documentation is usually the /last/ thing to be addressed 
with most projects and everyone hates to do it ;-)

Post a reply to this message

"Alain" <aze### [at] qwertyorg> wrote in message 
news:4ddb1917$1@news.povray.org...
> Le 2011/05/23 21:21, SGeier a écrit :
[...]>>>>     [OBJECT_MODIFIERS...]
>>>>     }
>
> Note that all items are lower case, then, you have OBJECT_MODIFIERS in all 
> UPPERCASE. This tells you that OBJECT_MODIFIERS is not in the same 
> category. In fact, it tells that OBJECT_MODIFIERS in not an item.

Pray tell. Could you imagine that this might be the case why I called it "a 
whole class of [object_modifiers]" in the paragraph directly following this 
(that you so politely quoted right here:)

>>>> This tells me that a number of items can occur inside the isosurface{}
>>>> entity. For example [threshold ...] or [contained_by ...] and a whole
>>>> class of [object modifiers].

Not that it has any bearing on this:

>>>> Nowhere in the docs is any mention that their order
>>>> matters in any way and as a matter of fact some of the examples in the
>>>> tutorial have them in an order different from the above.
>
> The documentations clearly state that all object modifiers must follow all 
> objects items.

It is good to hear that there is at least one thing that the documentation 
"clearly states". Because most parts of the documentations are rather 
unclear.

Surely it wouldn't be too much of a bother if you could kindly direct me to 
the section in the documentation that "clearly states" such a thing? It 
seems that I keep missing all the important parts of the docs and I'd like 
to make sure I have read at least those parts that clearly state things.

[...]
> You seems to confuse "items" and "modifiers".
> Items can be in any order.
> Modifiers also can be specified in about any order. They also MUST follow 
> the last item.

The word "item" has a fairly well-established meaning in the English 
language, a meaning that would make every "thing" inside the {}, including 
any modifier, an "item". If the POV-Ray docs would like the reader to 
understand the term it in a manner incompatible with the common meaning then 
I'm sure they "clearly state" such a thing. Could you please simply tell me 
where I should go to find that?

[...]
>>> "SGeier"<som### [at] somewherecom>  wrote in message
>>> news:<4dd316e8$1@news.povray.org>...
>>
>>> OK, I'm either doing something phenomenally stupid, or there's a blatant
>>> bug
>>
>>> in isosurface{} in 3.7rc3.
> You asked if there was a bug, and there is none.
> It leaves the "something phenomenally stupid" part...

As it turns out there was a third possibility: the documentation is wrong.

This is clearly a problem with my expectations: when I use the RC of some 
software, I expect to find a bug here'n'there. And maybe possibly that I'm 
just using the software wrong. I don't really expect to find documentation 
that

- doesn't document the behaviour of the software correctly AND
- doesn't express the intent of the programmers

[...]
 >>Turns out what I was
>> *really* bumping into was about some subtle distinction about the items I
>> can put into an isosurface{} statement, namely that some of them are
>> "object_modifiers" and assume a special place, while others are
>> object-specific and can go wherever.
>
> Again, "object_modifiers" are not items. It thus don't follows the general 
> rule of order as the items.
>

Oh, so there is such a thing as a "general rule of order"? Surely you can 
point me to the part of the documentation that expresses that rule, right?

And if object_modifiers *must* be in a certain position because they *don't* 
follow that "general rule", then I am concluding that the "general rule" is 
that I can put items into any order? Because that seems to be in direct 
contradiction with Christian Froeschlin's claim "in absence of special 
syntax, everything is to be taken literally and in the order specified."

[...]
> This is that way at least since version 1.
>
> primitive_name{mendatory_items [optional_items_in_any_order] 
> [OBJECT_MODIFIERS_IN_ANY_ORDER]}

That line there - can you show me where I can find that in the docs? 
Obviously it must be in there somewhere if it has been that way since 
version 1. Thanks.

> If you look around, you'll find that:
> Most of the time, max_gradient immediately FOLLOWS the function. It's 
> question of style and general concensus.
> Also, most of the time, contained_by is the last isosurface parameter. 
> Also a question of style and concensus.

And where, exactly, would I do that "looking around" thing you're talking 
about? The newsgroups have very little POV code on them, and where they do 
it's usually someone posting something that *doesn't* work.

I guess the obvious place would be the "code samples" section of the 
documentation. Oh, sorry, there is no such section. Hummm ...

> max_trace_level apply exclusively to transparency and reflections, never 
> ever to any surface that can never be visible.

I think you might benefit from reading the actual message I posted here that 
started the thread. It would allow you to make comments that have a bearing 
on the matter at hand. The suface I was writing about  was perfectly visible 
*if* it was encased in a transparent object. It vanished when the enclosing 
transparent object was removed. The issue is thus *very much* one of 
"transparency and reflection" and nobody here anywhere wrote about a surface 
"that can never be visible".

It would be possible to *make* the surface in question "never be visible" by 
setting
 global_settings {max_trace_level 1}

> max_trace/all_intersections is very different and there is no "magic" 
> transforming one into the other.
> max_trace_level is a global setting that affect the evaluation of tracing 
> rays.
> max_trace is an object attribute specific to the isosurface in exactly the 
> same way that max_gradient is. It affect how the isosurface is evaluated 
> if there are surfaces that can't be seen. Please note that ther is NO 
> "_level" here. They do LOOK similar, but are totaly different things.

Both are instructions that tell POV-Ray how many ray-surface intersections 
to follow before giving up.

I am at a loss how a sentient being can claim that they are "totally 
different things".

Post a reply to this message

Le 2011/05/24 20:55, SGeier a écrit :
> "Alain"<aze### [at] qwertyorg>  wrote in message

>> The documentations clearly state that all object modifiers must follow all
>> objects items.
>
> It is good to hear that there is at least one thing that the documentation
> "clearly states". Because most parts of the documentations are rather
> unclear.

Maybe if you look in the documentations for object modifiers...
You'll see that clipped_by IS an object modifier.
You'll also see, at the top, that object modifiers must be at the end of 
any object's definition.


>
> I am at a loss how a sentient being can claim that they are "totally
> different things".
>
>

max_trace_level (default value 5) is how many ray-surface to follow when 
you have refraction or reflection. Each surface do have an effect on the 
value of a specific pixel. In 3.7, contrary to versions 3.6.2 and 
earlier, plain transparent surfaces that don't reflect nor refract are 
not counted against max_trace_level.
When you exeed max_trace_level, the colour returned is black (rgb 0).

max_trace (default value 1) is, for an isosurface in a CSG, how many 
surface to EVALUATE or FIND. Here, the crossed surface don't have ANY 
effect when computing the falue of a pixel.

If you set max_trace_level 1, it means that you stop following new rays 
after the first reflection or refraction. You'll get black instead of 
reflection or refractions.

With max_trace 1, the second and successive surfaces are not evaluated. 
That means that you don't find when you exit the isosurface.

Post a reply to this message

"Alain" <aze### [at] qwertyorg> wrote in message 
news:4ddd2c02$1@news.povray.org...
> Le 2011/05/24 20:55, SGeier a écrit :
>> "Alain"<aze### [at] qwertyorg>  wrote in message
>
>>> The documentations clearly state that all object modifiers must follow 
>>> all
>>> objects items.
>>
>> It is good to hear that there is at least one thing that the 
>> documentation
>> "clearly states". Because most parts of the documentations are rather
>> unclear.
>
> Maybe if you look in the documentations for object modifiers...
> You'll see that clipped_by IS an object modifier.


OK, I am rapidly losing my patience here. The following is a cut-and-paste 
of the complete pertinent sections of the *currently shipping* 3.7RC3 
windows help file:

============== begin cut/paste =============================
3.4.9 Object Modifiers
A variety of modifiers may be attached to objects. The following items may 
be applied to any object:

OBJECT_MODIFIER:
  clipped_by { UNTEXTURED_SOLID_OBJECT... } |
  clipped_by { bounded_by }                 |
  bounded_by { UNTEXTURED_SOLID_OBJECT... } |
  bounded_by { clipped_by }                 |
  no_shadow                  |
  no_image [ Bool ]          |
  no_radiosity [ Bool ]     |
  no_reflection [ Bool ]     |
  inverse                    |
  sturm [ Bool ]             |
  hierarchy [ Bool ]         |
  double_illuminate [ Bool ] |
  hollow  [ Bool ]           |
  interior { INTERIOR_ITEMS... }                        |
  material { [MATERIAL_IDENTIFIER][MATERIAL_ITEMS...] } |
  texture { TEXTURE_BODY }   |
  interior_texture { TEXTURE_BODY } |
  pigment { PIGMENT_BODY }   |
  normal { NORMAL_BODY }     |
  finish { FINISH_ITEMS... } |
  photons { PHOTON_ITEMS...}
  radiosity { RADIOSITY_ITEMS...}
  TRANSFORMATION
Transformations such as translate, rotate and scale have already been 
discussed. The modifiers Textures and its parts Pigment, Normal, and Finish 
as well as Interior, and Media (which is part of interior) are each in major 
chapters of their own below. In the sub-sections below we cover several 
other important modifiers: clipped_by, bounded_by, material, inverse, 
hollow, no_shadow, no_image, no_reflection, double_illuminate and sturm. 
Although the examples below use object statements and object identifiers, 
these modifiers may be used on any type of object such as sphere, box etc.

3.4.9.1 Bounded_By
[...]

3.4.9.2 Clipped_By
The clipped_by statement is technically an object modifier but it provides a 
type of CSG similar to CSG intersection. The syntax is:

CLIPPED_BY:
  clipped_by { UNTEXTURED_SOLID_OBJECT... } |
  clipped_by { bounded_by }
Where UNTEXTURED_SOLID_OBJECT is one or more solid objects which have had no 
texture applied. For example:

object {
  My_Thing
  clipped_by{plane{y,0}}
  }
Every part of the object My_Thing that is inside the plane is retained while 
the remaining part is clipped off and discarded. In an intersection object 
the hole is closed off. With clipped_by it leaves an opning. For example the 
following figure shows object A being clipped by object B.

[image here]

You may use clipped_by to slice off portions of any shape. In many cases it 
will also result in faster rendering times than other methods of altering a 
shape. Occasionally you will want to use the clipped_by and bounded_by 
options with the same object. The following shortcut saves typing and uses 
less memory.

object {
  My_Thing
  bounded_by { box { <0,0,0>, <1,1,1> } }
  clipped_by { bounded_by }
  }
This tells POV-Ray to use the same box as a clip that was used as a bound.

3.4.9.3 Double_Illuminate
[...]
==================== end cut/paste ======================

> You'll also see, at the top, that object modifiers must be at the end of 
> any object's definition.
>

No, I will NOT see that because it is NOT in the documentation.

At this point, there are two possiblities left:

1) You have no idea what is actually in the documentation and you cannot be 
bothered to look it up and actually inform yourself OR

2) You are deliberately lying

Either way, you are NOT qualified to tell other people who have actually 
LOOKED at the documentation what is or isn't supposedly in there.

I asked you for pointers to *several* things you claimed were allegedly in 
the documentation.

You provided *none*.

I do not know what you imagine you're accomplishing by this, but neither 
POV-Ray, nor the POV-Ray documentation, nor myself or the dev-team benefit 
from people making *false* claims about what is actually in the actual 
documentation.

Post a reply to this message

"clipka" <ano### [at] anonymousorg> wrote in message 
news:4ddc4488$1@news.povray.org...
> Am 24.05.2011 03:21, schrieb SGeier:
>> No, it is not an assumption. It is an *observation*.
>
> It's an observation that /some/ items can be specified in arbitrary order 
> (and as a matter of fact happens to be true for all non-OBJECT_MODIFIER 
> items). However, it was only your /assumption/ that it was also true for 
> /all/ items including OBJECT_MODIFIER elements.

When I *should* have assumed that it is true for all items *except* 
object_modifiers?

Seriously?

You *document* (in words) that there's a bunch of parameters and you 
*document* (by example) that they can be used in different order but there's 
a problem with *my assumption* because I didn't expect *undocumented* 
exceptions to *documented* behaviour?

Maybe you should take a step back yourself and ask yourself what you imagine 
you're accomplishing with this bullshit.

> That said, rather than continuing this interesting nitpicking contest, 
> please take a step back, rethink, and tell us what you /want/ from the dev 
> team.

Here's one thing I definitely want from the dev team: Stop lying. Neither 
the program nor the docs nor me nor you benefit from post after post after 
post of claims of this-or-that things that are allegedly "clearly 
documented" that nobody can *show* or *point to* because they *doesn't 
exist*.

3) The POV-Ray documentation is
   *one* *hairy* *clusterfuck*
  (pardon the language, I already toned this down)

POV-Ray is one of the three worst-documented software projects I have ever 
encountered. The other two are samba and ntp. Notice a commonality here? 
Each of these three comes with megabyte upon megabyte of "documentation" 
that *carefully avoids* ever actually spelling anything out. Ever providing 
any actual information. Ever explaining the simple basics.

The reason for this sorry state is

2) The POV-Ray Scene Description Language is
    *one* *hairy* *clusterfuck*

I've written code in languages that require a semicolon at the end of a 
statement. Languages that don't. Languages that allow semicolons but don't 
require them. But POV-Ray is the only language known to me that makes a 
semicolon mandatory for *some* statements, optional for *some* others and 
throws a parse error for yet some others. Some day I'll end a statement with 
", please" and I half expect that to actually work.

Abnd the reason for *that* is

1) POV-Ray was cobbled together over two decades without any kind of 
unifying style document. Various people with various motivations keep adding 
and patching and fiddling and there is no steering committee or mission 
statement or anything that would lead to a self-consistent syntax, 
self-consistent grammar, self-consistent semantics. There is no Persistence 
of Visison of the developers. "Hey, I'd like xyz feature"; "you're welcome 
to write the code for it"; "Oh, ok, I added a flag to the crackle pattern to 
do it".

They're numbered in causal order, as far as I can discern it.

#3 could be massively improved by the developers if only they could be arsed 
to actually *look* at the documentation. Not tell people "xyz is in the 
docs", which doesn't help anybody. Half the time is is NOT in the docs, and 
the other half the correct response is "where in the docs did you look and 
how did you interpret this-or-that sentence" and then move the information 
that people are looking for where people expect it.

There's nothing wrong with the line
   objectName {mandatoryItems [optional items in any order] [object 
modifiers in any order]}

Why is that line not in the docs? Why is there *nothing* in the docs that 
simply documents what the parser expects and when and where?

Simple exercise: Create a document that brings someone up-to-speed who's 
never touched POV-Ray and wont be able to get back to you to ask questions. 
You have, say, 10 pages to write everything a new user needs to know. No 
more. No megabytes of tutorials. And no, not a "quick reference" either: You 
will have to write the sentences that the current docs lack: "Every scene 
needs a camera, should probably have at least one object of some sort so 
there's something to look at and usually should probably also have a 
light_source". That's one-and-a-half lines of text and it contains more 
information than the first ten pages of the POV-Ray docs combined.

Other simple exercise: install the windows version, hit F1, start reading at 
the beginning: Section 1.1 Introduction. The docs call themselves a "book", 
and that's how you read a book. The goal is to read until you have read 
everything you need to render your first scene (no, the demo doesn't count. 
Your *own* first scene). Pages upon pages upon pages upon even more pages of 
blah-blah without any kind of content. If your goal is to *make* people skip 
whole sections of the docs, congrats: you've succeeded. But seriously: keep 
reading. And reading. I think you get all the tools to render a simple scene 
somewhere around section 2.2, so just keep reading.

#2 Is harder, but would require little more than all dev-folks coming 
together and laying out how POV-Ray is actually *supposed* to work. Spell it 
out *without* writing code: How do you want things to happen, how should 
they be structured.

Then implement what you decided.

No sane developer will *design* a language where some statements *must* 
start with a "#", while some others *can* have a "#" at the beginning. 
"sphere" and "#sphere" are both acceptable, "declare" throws a warning but 
works, "if" is an error. That's just absurd. Some mechanisms take parameters 
in {} braces, others take them in () brackets. Some places take "x" to be a 
unit vector, some others interpret it as a float. *Of course* the 
documentation is going to be complete bullshit if the thing to be documented 
is bullshit.

Just in this one thread I've heard from one person that there is a supposed 
"general rule" of order that is that everything can be in arbitrary order 
except for object_modifiers and from another person that "unless there is 
special syntax, everything should be taken literally in the order given". 
These two are in mutual contradiction. NEITHER of these two can be found in 
the documentation. This is where I'd want the developers to talk amongst 
each other and decide which of these behaviours they actually *want*, then 
*implement* that and then *document* it.

Yes, this would require that the developers negotiate amongst themselves 
what it is that they actually want.

And then they'd have to implement it, which I'm sure is less fun than just 
will-nilly throwing yet-another-interpretation of some identifier into the 
parser. But that way someone starting to tinker with POV-Ray could actually 
stand a chance of discerning what is *supposed* to happen, since there would 
in fact be something that *is* *supposed* to happen.

POV-Ray has had two decades for the various shifting dev-teams to come to 
*some* basic understanding of how things *should* happen. A brief style 
manual. Some outline what the syntax rules should be. What the actual rules 
of the parser should be. Something against which it can be measured whether 
or not adding yet another keyword-with-its-own-incompatible-sub-syntax is 
the right thing to do.

And it is pretty clear that none of that ever happened.

> Yes, the docs badly do need some improvement, but (1) that's not a new 
> issue caused by the 3.6 -> 3.7 transition, and (2) it's not realistically 
> achievable with just adding a bit of more patchwork here and there; what's 
> really necessary is a systematic overhaul, which will possibly include a 
> major rewrite and/or restructuring of many sections.

Step one will be convincing your fellow developers that this is true --  
because they seem to *imagine* that the documentation is great and contains 
all kinda of wonderful things. And they cannot be arsed to read the docs 
themselves to see what a sorry state they're really in.

Step two will be for you to realize that half of the sorry state of the docs 
is a reflection of the sorry state of the parser.

OK, you asked what I want, here I told you.

I'm not necessarily expecting to get all (or any) of that, I'm merely 
answering your question.

Now the *REASON* I want all this is because POV-Ray *could* fill a niche if 
only it worked (and that includes working documentation and a working 
feedback mechanism where developers don't just simply *deny* the reality 
everybody can see with their own eyes).

The concept of a fully analytic ray-tracer is appealing. Yes, I could get 
Blender and start throwing meshes around. I might end up doing that. Like 
many people before me. But I still think the basic *idea* behind POV-Ray is 
sound. I *like* POV-Ray, or I wouldn't come back once a year for year after 
year. But after sufficiently many years I see the execution *bungled* by 
developers who think as long as they had their fun writing code, nothing 
else matters. Screw the users.

Post a reply to this message

Le 26/05/2011 02:47, SGeier a écrit :
> No, I will NOT see that because it is NOT in the documentation.
> 

Instead of focusing your rage on this thread, what about using all that
energy to contribute to the documentation itself (on the pov-wiki pages)?

I'm sure you know the right spot to add or amend a paragraph or two
about the behaviour you observed (i.e. all specific object options must
be before the very first option from OBJECT_MODIFIER). At least you
would be expecting it there, so, in fact, you do know that place.

> I asked you for pointers to *several* things you claimed were allegedly in 
> the documentation.

I used to know the povray documentation by heart... but it was at the
time of 3.1 (well, I started with 2.12 of something not called povray).

I get a bit lost with the 3.5 and further. (and it seems there is
duplicate data for the SDL: often in the object description, and later
in the SDL summary. It's like having two watches (clock), if they are
different, I'm unable to know which one is true (if any)).

I would reckon (but I'm not able to provide a better tool) that the
search engine on the wiki is far too weak, at least for my taste, i'm
never able to find a good match. I might not be using the right wordings.

-- 
Software is like dirt - it costs time and money to change it and move it
around.

Just because you can't see it, it doesn't weigh anything,
and you can't drill a hole in it and stick a rivet into it doesn't mean
it's free.

Post a reply to this message