Re: [GRASS-dev] Display library documentation?

[Glynn Clements]

Moritz Lennert wrote:

> Glynn, as you are the one who significantly rewrote the display library, 
> do you have any documentation or notes stored somewhere ?

No. And I'm not familiar with the parts related to symbols; I haven't
touched that (beyond keeping it in sync with other changes to the
display library).

So far as coordinates go, for drawing geographic data, the usual
procedure is to call D_setup() and use cartographic coordinates
directly. For other data (e.g. legends), D_setup2() sets a
user-defined coordinate system while D_setup_unity() allows screen
coordinates to be used directly.

The library deals with 3 coordinate systems:

U (user) coordinates are used by most D_* functions which take
coordinates (the exceptions being the functions which convert
coordinates from other coordinate systems).

A (array) coordinates correspond to the region grid, and are used
implicitly for drawing raster data.

D (display) coordinates are screen pixel coordinates. The display
library converts U and A coordinates to D coordinates, which are
passed to driver functions (COM_*).

The low-level functions for setting coordinate systems and performing
conversions are in cnversions.c. Higher-level convenience functions
for setting coordinate systems are in setup.c.

D_setup() sets the U coordinate system to cartographic coordinates so
that the current region fits exactly inside the current display frame
while maintaining aspect the ratio.

D_setup2() sets the U coordinate system to a user-defined coordinate
system so that the specified rectangle fits exactly inside the current
display frame while optionally maintaining the aspect ratio.

D_setup_unity() sets the U coordinate system to match the D coordinate
system. This exists mainly to simplify the transition for existing
code.

-- 
Glynn Clements 
___
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

Re: [GRASS-dev] Display library documentation?

[Moritz Lennert]

On 16/09/15 01:53, Vaclav Petras wrote:



On Tue, Sep 15, 2015 at 6:06 AM, Moritz Lennert
> wrote:

On 14/09/15 15:53, Vaclav Petras wrote:

Hi,

is there some documentation on how to use the display library,
i.e. how
to write a d.* module?


I imagine you looked at
https://grass.osgeo.org/programming7/displaylib.html ?


I've tried reading d.vect code but I miss the
general rules and concepts like how to set color or which
coordinates


Have you checked display_shape() in shape.c and the individual
display_* functions in the relevant files (area.c, line.c) for the
different types of features ?

The color is set with D_RGB_color which takes a color struct as input.
Then the feature is drawn with
D_polygon_abs/D_polyline_abs/D_polydots_abs which take the
coordinates from the line struct Points which is filled with info
using Vect_read_line().

should be used when as well as information which functions should be
used in which case like what is the difference between D_symbol and
D_symbol2.


 From the programmer's manual section on D_Symbol2:

"The same as D_symbol(), but it uses a primary and secondary color
instead of line and fill color. "



Thanks Moritz, this is approximately as far as I got. I hoped I over
looked something but apparently not. The documentation is in Doxygen
format but it is just a list of functions. What is primary and secondary
color, I can only guess from context, etc. and your sentence about
feature drawing is the most detailed documentation we have now for the
display library.

So, I think that we have a big problem. It seems that the display
library, despite its crucial role, is the most underdocumented library
we have. In fact it is not documented at all. Others have some readmes
with basic workflow, comments for functions or comments in code. Display
library has nothing. Because of the level of abstraction for different
drivers, its hard, at least for me, to guess the rules or even best
practices for usage and because of the complexity or specificity of
display modules, its hard to guess what is the general and effective way
of doing things.

Please, can somebody with some experience document some functions,
provide examples or a complete d.example module? When having at least
something I can then help with formatting or examples.




Glynn, as you are the one who significantly rewrote the display library, 
do you have any documentation or notes stored somewhere ?


Moritz
___
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

Re: [GRASS-dev] Display library documentation?

[Vaclav Petras]

On Tue, Sep 15, 2015 at 6:06 AM, Moritz Lennert <
mlenn...@club.worldonline.be> wrote:

> On 14/09/15 15:53, Vaclav Petras wrote:
>
>> Hi,
>>
>> is there some documentation on how to use the display library, i.e. how
>> to write a d.* module?
>>
>
> I imagine you looked at
> https://grass.osgeo.org/programming7/displaylib.html ?
>
>
> I've tried reading d.vect code but I miss the
>> general rules and concepts like how to set color or which coordinates
>>
>
> Have you checked display_shape() in shape.c and the individual display_*
> functions in the relevant files (area.c, line.c) for the different types of
> features ?
>
> The color is set with D_RGB_color which takes a color struct as input.
> Then the feature is drawn with D_polygon_abs/D_polyline_abs/D_polydots_abs
> which take the coordinates from the line struct Points which is filled with
> info using Vect_read_line().
>
> should be used when as well as information which functions should be
>> used in which case like what is the difference between D_symbol and
>> D_symbol2.
>>
>
> From the programmer's manual section on D_Symbol2:
>
> "The same as D_symbol(), but it uses a primary and secondary color instead
> of line and fill color. "



Thanks Moritz, this is approximately as far as I got. I hoped I over looked
something but apparently not. The documentation is in Doxygen format but it
is just a list of functions. What is primary and secondary color, I can
only guess from context, etc. and your sentence about feature drawing is
the most detailed documentation we have now for the display library.

So, I think that we have a big problem. It seems that the display library,
despite its crucial role, is the most underdocumented library we have. In
fact it is not documented at all. Others have some readmes with basic
workflow, comments for functions or comments in code. Display library has
nothing. Because of the level of abstraction for different drivers, its
hard, at least for me, to guess the rules or even best practices for usage
and because of the complexity or specificity of display modules, its hard
to guess what is the general and effective way of doing things.

Please, can somebody with some experience document some functions, provide
examples or a complete d.example module? When having at least something I
can then help with formatting or examples.

Thanks,
Vaclav
___
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

Re: [GRASS-dev] Display library documentation?

[Moritz Lennert]

On 14/09/15 15:53, Vaclav Petras wrote:

Hi,

is there some documentation on how to use the display library, i.e. how
to write a d.* module?


I imagine you looked at 
https://grass.osgeo.org/programming7/displaylib.html ?




I've tried reading d.vect code but I miss the
general rules and concepts like how to set color or which coordinates


Have you checked display_shape() in shape.c and the individual display_* 
functions in the relevant files (area.c, line.c) for the different types 
of features ?


The color is set with D_RGB_color which takes a color struct as input.
Then the feature is drawn with 
D_polygon_abs/D_polyline_abs/D_polydots_abs which take the coordinates 
from the line struct Points which is filled with info using 
Vect_read_line().



should be used when as well as information which functions should be
used in which case like what is the difference between D_symbol and
D_symbol2.


From the programmer's manual section on D_Symbol2:

"The same as D_symbol(), but it uses a primary and secondary color 
instead of line and fill color. "


Moritz


___
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

[GRASS-dev] Display library documentation?

[Vaclav Petras]

Hi,

is there some documentation on how to use the display library, i.e. how to
write a d.* module? I've tried reading d.vect code but I miss the general
rules and concepts like how to set color or which coordinates should be
used when as well as information which functions should be used in which
case like what is the difference between D_symbol and D_symbol2.

Thanks,
Vaclav
___
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev