[raster] ST_Addband() should be in the "Raster Constructors" part of the documentation

[pracine]

And ST_Band() should be in the "Raster Band Accessors" section.

Actually the "Raster Band Accessors and Constructors" section should be renamed just "Raster Band Accessors" as there is another "Raster Constructors" section.

Or merge everything together….

[robe]

Pierre, Hope this is what you had in mind. I've moved ST_AddBand to Raster Constructors and renamed Raster Band Accessors and Constructors to just Raster Band Accessors.

Raster accessors was there to hold simple accessors that access properties of the overall raster e.g. the srid, dimensions etc.

Raster Band Accessors / Constructors was to access things specific to a band, but since a band is not itself an object (as I think we had originally thought we would have) returning a band IS returning a raster so there is no such thing as a Raster Band Constructor though you can access properties of an individual band. I must have thought that all along since the anchor tag was Raster_Band_Accessors

Feel free to reopen if you are not satisfied with this solution.

[robe]

forgot at r7974

[pracine]

I still think it would make more sense to put ST_Band() in the "Raster Band Accessors" section… Isn't ST_band() just a "Raster Band Accessors" itself?

[robe]

No — accessors are relegated to simple accessors that return numbers, text, etc.

That's my definition and I'm sticking by it.

Look at the PostGIS geometry section for example — you see any accessor returning anything complex.

​http://www.postgis.org/documentation/manual-svn/reference.html#Geometry_Accessors

Besides there is no such thing as a band object. That function returns a new raster.

[robe]

ah okay I misspoke. There is the ST_GeometryN and ST_InteriorN that return geometries.

Those actually I think are missplaced so I will move them when I get around to it.

[pracine]

Seems counter intuitive to me.

When I do ST_Band() I access a band. I do not construct a new raster more than I construct a new number when I do ST_SRID().

[robe]

Hmm those don't really fit in any other place (geometry) so I guess I'll have to rethink my definition of accessors.

How about we just get rid of Raster Band Accessors section and combine it so its

Raster Accessors. I never liked that separation. Because a Band does not exist as a bonafide object. It would be like having a Patches accessors or InteriorRingN accessors section. Too much minutiae.

When you do ST_Band() — YOU ARE creating a new raster like it or not. You are taking a subset of your raster and making a new raster. It's not even a pointer its a copy of the sections of your original raster.

[pracine]

Replying to robe:

Hmm those don't really fit in any other place (geometry) so I guess I'll have to rethink my definition of accessors.

How about we just get rid of Raster Band Accessors section and combine it so its

Raster Accessors. I never liked that separation. Because a Band does not exist as a bonafide object. It would be like having a Patches accessors or InteriorRingN accessors section. Too much minutiae.

When you do ST_Band() — YOU ARE creating a new raster like it or not. You are taking a subset of your raster and making a new raster. It's not even a pointer its a copy of the sections of your original raster.

When you are doing ST_SRID() — YOU ARE creating a new number like it or not.

To me accessors are getters of existing objects part of others. Constructors starts from nothing which was this kind of object before (geometries from numbers, rasters from numbers).

Also sometimes you speak about "Settors" and sometimes about "Editors". To me all "set" functions should just be "Editors" and "get" function (that get an existing part of an object without modifying it) should be "Accessors". Then you get different levels of access: raster, band, pixel or specific categories (like the ones for stats, processing or outputs).

I would also rather call "Outputs" "Converters"…

What about definitions like this:

Management - Functions to manage the database structure or get info about non geographical objects.

XXX Construction - Functions to create new XXX.

XXX Property - Functions returning XXX properties (or parts of XXX properties) (implying or not a computation - commonly knows as getters).

XXX Edition - Functions to edit XXX properties.

XXX Process - Functions to tranform or process XXX objects (or parts of XXX objects) into new XXX objects.

XXX Conversion - Functions to convert XXX objects into other equivalent objects.

XXX Operators - Spatial relationship operators.

XXX Spatial Relationship - Boolean functions returning the status of a spatial relationship.

XXX Metric - Functions returning a measure.

XXX Statistic - Function returning computed statistics related to a geographical object (or a part of a geographical object).

Some specific sections are possible for groups of function doing specific things ("Linear referencing").

XXX could be replaced with "Geometry", "Geography", "Raster", "Raster Band" or "Raster Pixel". I don't know how you managed the geography type though.

The "XXX Property" section could be splitted into "XXX Property" and "XXX Derived Property" for properties implying a computation of some sort like ST_Boundary(), ST_IsClosed(), ST_IsValid(), etc… But then it would become hard to distinguish them from the Process functions…

I would drop the word "Function" from the sections titles as they are all functions anyway and we know it (now sometimes it's there and sometimes it's not there).

I would guess "Operators" forced you to give "ors" names to every sections (like "EditORS" - I don't know the specific name of that kind of name) but since it does not work in many cases (Spatial RelationshipORS!!!) I would rather keep this form only for "Operators" and give category like named to sections like I did above.

With those definitions applied to the "PostGIS Reference" section:

-The Spatial relationship functions would be separated from the Measurements ones - which I think is very good. -All the ST_XMin, ST_YMin, ST_XMax, etc. miscellaneous functions should go in the "XXX Property" since they are like those implying a computation. -Find_SRID() should go in the "Management" section. -Actually all the "Miscellaneous Functions" should find a place somewhere in the "Management" or the "XXX Property" section if you accept that some of the "XXX Property" are computed (e.g. ST_MemSize() should go in the "XXX Property" section). -A better analysis would probably determine other changes.

I think the harder things to distinguish are "Process" functions from some "derived" Properties functions (e.g. ST_ConcaveHull() VS ST_Boundary() and ST_NumGeometries() VS ST_Dump()). We might want to precise both definitions to solve this.

I would add the section definition in the doc itself so don't lose them and we can refer to them to identify a misclassification.

Sorry to open a Pendora's box but I always found that the classification was a bit lame…

[robe]

Pierre, My point is there is NO SUCH THING as a RASTER BAND object so its silly to have a category for it unless you create such as thing.

It sounds like you are really dying to edit this stuff yourself. Feel free to. Then you can come up with any categorization you like .

I agree things are too broken up and part of that was just like that before I got here so didn't really make any fuss about it since its a bit of a hassle to shuffle things into categories that are just as illogical as what categories are there. It hurts my brain too much to think about this categorization stuff. I'm all for fewer categories than more so the more we can compress the better. Almost tempted to get rid of the whole categorization model entirely.