[NTG-context] Seeking advice for module that draws globes

[NTG-context] Seeking advice for module that draws globes

[Gavin via ntg-context]

[-- Attachment #1: Type: text/plain, Size: 948 bytes --]

Hello ConTeXters,

I wrote a little ConTeXt module for drawing globes. I would love some advice on how to improve it and share it. The code is quite short (about 250 lines). Most of the work is done by Lua, which reads the data files and calculates paths. These paths are passed to MetaFun, which draws the globe.

Below is an example document with the output. (I attached a small .png of the output for the mailing list. The output PDF has excessive detail.) The module (code and data) is on GitHub at https://github.com/GavinPolhemus/luageo.

\usemodule [luageo]
\startMPpage
    GlobeDiameter = 10cm ;
    fill fullcircle scaled GlobeDiameter withcolor .9white ;  % Fill a circle with the water color.
    drawglobe(23, 0) scaled GlobeDiameter withcolor .75white ;% Draw the land, centered on the given latitude and longitude.
    draw fullcircle scaled GlobeDiameter withcolor black ;    % Add a border, if you want.
\stopMPpage


[-- Attachment #2: luageoTestMPpage.png --]
[-- Type: image/png, Size: 28342 bytes --]

[-- Attachment #3: Type: text/plain, Size: 2671 bytes --]



I am a novice at both Lua and MetaPost. I’m also new to Git and have never shared anything of substance with the ConTeXt community. (This barely counts as substantive, but I figure it’s best to start small.) I’m sure many of you could find opportunities for improvement with even a quick glance at the code. I welcome anything, from advice on performance to suggestions about the license. My most pressing questions are these:

1. How do I avoid redrawing diagrams with every typeset? The globe above takes about 0.7s, which is not bad, but it adds up in a book with many diagrams.

2. How do I organize this according to TDS for sharing? I know what TDS is and why it’s important, but that’s about it!

3. Should I be creating a namespace for this module, or launching a separate MetaFun instance? I have a general sense of what “namespace” and “instance” mean is this context, but I don’t know the consequences or the how-to.

I’d like to share this module, even though the potential demand is tiny, at best. I’m going through the Module Writing Guidelines (https://wiki.contextgarden.net/Modules#Module_writing_guidelines), but there is a lot that I don’t understand in those instructions. Questions 2 and 3 above relate to the instructions that are most mysterious to me. I think I can figure most of the others out.

I have been using ConTeXt for several years to write a high school physics textbook (along with the problem sets, tests, equations sheets, etc.). I wrote this module because I needed globes in some diagrams. I found an old MetaPost tool, mp-geo, that seemed to have the right ingredients, but I couldn’t get it to work, so I wrote my own tool using the data files from mp-geo. Hans and others on the list gave me valuable advice for these globes a couple years ago (and gave other valuable advice on all sorts of things before and since).

Many diagrams in my physics book use TikZ and pgfplots. I'd like to convert everything to MetaFun. I think the best way will be writing a few more modules for things like graphs (including polar and 3D plots), simple circuits, simple Feynman diagrams, etc. I’m hoping that these would be useful to the ConTeXt community. The luageo module has the basic design I’d like to use for the others: Lua for data handling and calculations, producing paths that are drawn by MetaFun. With some mentoring from the generous ConTeXt community, I’m hoping we can provide MetaFun alternatives to some of the TikZ libraries.

I have an alpha version of luagraph by Alan Braslau, which was helpful in designing luageo. Working on luagraph is my next project.

Gavin



[-- Attachment #4: Type: text/plain, Size: 511 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Hans Hagen via ntg-context]

On 12/17/2023 11:22 PM, Gavin via ntg-context wrote:

> 1. How do I avoid redrawing diagrams with every typeset? The globe above takes about 0.7s, which is not bad, but it adds up in a book with many diagrams.

\startbuffer[demo]
\usemodule [luageo]
\startMPpage
     GlobeDiameter = 10cm ;
     fill fullcircle scaled GlobeDiameter withcolor .9white ;  % Fill a 
circle with the water color.
     drawglobe(23, 0) scaled GlobeDiameter withcolor .75white ;% Draw 
the land.
     draw fullcircle scaled GlobeDiameter withcolor black ;    % Add a 
border, if you want.
\stopMPpage
\stopbuffer

\typesetbuffer[demo]

> 2. How do I organize this according to TDS for sharing? I know what TDS is and why it’s important, but that’s about it!

Hraban will guide you here.

> 3. Should I be creating a namespace for this module, or launching a separate MetaFun instance? I have a general sense of what “namespace” and “instance” mean is this context, but I don’t know the consequences or the how-to.
If the code is robust there is no need for an instance.

Hans


-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Hans Hagen via ntg-context]

On 12/17/2023 11:22 PM, Gavin via ntg-context wrote:
> Hello ConTeXters,
> 
> I wrote a little ConTeXt module for drawing globes. I would love some advice on how to improve it and share it. The code is quite short (about 250 lines). Most of the work is done by Lua, which reads the data files and calculates paths. These paths are passed to MetaFun, which draws the globe.

Just some quiks remarks ...

- you use the right strategy (tex/lua/mp)

- in mp you can do this

vardef theglobe(expr lat, lon) =
     for i = 1 upto lua.mp.makeglobe(lat, lon):
         (lua.mp.getglobepath(i)) &&&&
     endfor
     cycle
enddef ;

and then:

\startMPpage
     GlobeDiameter = 10cm ;
     fill fullcircle
         scaled GlobeDiameter
         withcolor .9white ;
     path p ; p := theglobe(23, 0)
         scaled .5GlobeDiameter
     ;
     draw p
         withpen pencircle scaled .2mm
         withcolor blue
         withtransparency (1,.5) ;
     fill p
         withcolor red
         withtransparency (1,.5) ;
     draw fullcircle
         scaled GlobeDiameter
         withcolor black ;
\stopMPpage

i use transparency to demo that a single path has advantages; you'll 
also notice that the runtime is actually at the mp end.

- in your lua code do this

local cosd = math.cosd
local sind = math.sind
local sqrt = math.sqrt

- also, use "MP.makeglobe" in the mp code and at the lua end function 
MP.makeglobe"" as that is the user namespace.

I'll mail you the lua file with some suggestions. When all is stable I 
can spend a few hours on optimizing if needed.

> I am a novice at both Lua and MetaPost. I’m also new to Git and have never shared anything of substance with the ConTeXt community. (This barely counts as substantive, but I figure it’s best to start small.) I’m sure many of you could find opportunities for improvement with even a quick glance at the code. I welcome anything, from advice on performance to suggestions about the license. My most pressing questions are these:

> 1. How do I avoid redrawing diagrams with every typeset? The globe above takes about 0.7s, which is not bad, but it adds up in a book with many diagrams.

see previous mail

> 2. How do I organize this according to TDS for sharing? I know what TDS is and why it’s important, but that’s about it!
> 
> 3. Should I be creating a namespace for this module, or launching a separate MetaFun instance? I have a general sense of what “namespace” and “instance” mean is this context, but I don’t know the consequences or the how-to.
> 
> I’d like to share this module, even though the potential demand is tiny, at best. I’m going through the Module Writing Guidelines (https://wiki.contextgarden.net/Modules#Module_writing_guidelines), but there is a lot that I don’t understand in those instructions. Questions 2 and 3 above relate to the instructions that are most mysterious to me. I think I can figure most of the others out.
> 
> I have been using ConTeXt for several years to write a high school physics textbook (along with the problem sets, tests, equations sheets, etc.). I wrote this module because I needed globes in some diagrams. I found an old MetaPost tool, mp-geo, that seemed to have the right ingredients, but I couldn’t get it to work, so I wrote my own tool using the data files from mp-geo. Hans and others on the list gave me valuable advice for these globes a couple years ago (and gave other valuable advice on all sorts of things before and since).
> 
> Many diagrams in my physics book use TikZ and pgfplots. I'd like to convert everything to MetaFun. I think the best way will be writing a few more modules for things like graphs (including polar and 3D plots), simple circuits, simple Feynman diagrams, etc. I’m hoping that these would be useful to the ConTeXt community. The luageo module has the basic design I’d like to use for the others: Lua for data handling and calculations, producing paths that are drawn by MetaFun. With some mentoring from the generous ConTeXt community, I’m hoping we can provide MetaFun alternatives to some of the TikZ libraries.

next year Mikael S and I are going to look into 3D (and projections) as 
we can only work on math when we have a parallel metafun pet project.

> I have an alpha version of luagraph by Alan Braslau, which was helpful in designing luageo. Working on luagraph is my next project.
> 
> Gavin
> 
> 
> 
> ___________________________________________________________________________________
> If your question is of interest to others as well, please add an entry to the Wiki!
> 
> maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
> webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
> archive  : https://github.com/contextgarden/context
> wiki     : https://wiki.contextgarden.net
> ___________________________________________________________________________________

-- 

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Gavin via ntg-context]

[-- Attachment #1: Type: text/plain, Size: 484 bytes --]

Hi Hans,

Thanks for all the suggestions! I am going through them carefully.

> - in mp you can do this
> 
> vardef theglobe(expr lat, lon) =
>    for i = 1 upto lua.mp.makeglobe(lat, lon):
>        (lua.mp.getglobepath(i)) &&&&
>    endfor
>    cycle
> enddef ;

Does "&&&&" allow a disconnected path? I haven’t seen "&&&&" or a disconnected path before.

Also, we do have a strange artifact, at least when I run this code. There is a line running across Brazil:


[-- Attachment #2: luageoTest.png --]
[-- Type: image/png, Size: 9789 bytes --]

[-- Attachment #3: Type: text/plain, Size: 273 bytes --]



I only got the line for (23,0), not for other latitude and longitude. I’m not sure what caused that. The code for cutting and mending paths that cross the horizon is tricky. I’m not sure how it will interact with "&&&&" and “cycle" connecting everything.

Gavin

[-- Attachment #4: Type: text/plain, Size: 511 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Henning Hraban Ramm]

Am 18.12.23 um 00:58 schrieb Hans Hagen via ntg-context:
> On 12/17/2023 11:22 PM, Gavin via ntg-context wrote:
>> 2. How do I organize this according to TDS for sharing? I know what 
>> TDS is and why it’s important, but that’s about it!
> 
> Hraban will guide you here.

I’ll try ;)

Hi Gavin, thank you for sharing this useful module!

Have a look at
https://wiki.contextgarden.net/Modules#Module_writing_guidelines
… and please tell me, if you miss anything or find errors!

Also look at the structure of other modules in the distribution, or e.g.
https://codeberg.org/fiee/context-simpleslides
This is how your code should be structured, i.e.
– LICENSE and README stay on top; add VERSION
– luageoTest.tex (and further documentation) goes into 
doc/context/third/luageo
– the rest goes into tex/context/third/luageo
– an interface file is optional

The publication process via https://modules.contextgarden.net is also 
outlined in the wiki page.

Best, Hraban
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Hans Hagen via ntg-context]

On 12/18/2023 4:49 AM, Gavin wrote:
> Hi Hans,
> 
> Thanks for all the suggestions! I am going through them carefully.
> 
>> - in mp you can do this
>>
>> vardef theglobe(expr lat, lon) =
>>     for i = 1 upto lua.mp.makeglobe(lat, lon):
>>         (lua.mp.getglobepath(i)) &&&&
>>     endfor
>>     cycle
>> enddef ;
> 
> Does "&&&&" allow a disconnected path? I haven’t seen "&&&&" or a disconnected path before.
> 
> Also, we do have a strange artifact, at least when I run this code. There is a line running across Brazil:
> 
> 
> 
> 
> I only got the line for (23,0), not for other latitude and longitude. I’m not sure what caused that. The code for cutting and mending paths that cross the horizon is tricky. I’m not sure how it will interact with "&&&&" and “cycle" connecting everything.
i'm not sure where that comes from (you can try &&&)

Hans


-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Hans Hagen via ntg-context]

On 12/17/2023 11:22 PM, Gavin via ntg-context wrote:
> Hello ConTeXters,
> 
> I wrote a little ConTeXt module for drawing globes. I would love some advice on how to improve it and share it. The code is quite short (about 250 lines). Most of the work is done by Lua, which reads the data files and calculates paths. These paths are passed to MetaFun, which draws the globe.
about names:

how about

t-luageo.lmt
t-luageo.mpxl

so that one knows what comes with the module (we do the same with s-* 
modules)

and you can add the example to the end of the module

\continueifinputfile{t-luageo.mkxl}

\starttext
	exaple code
\stoptext

and then process the module to get the example

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Gavin via ntg-context]

[-- Attachment #1: Type: text/plain, Size: 923 bytes --]

Hi Hans,

> On Dec 18, 2023, at 3:12 AM, Hans Hagen via ntg-context <ntg-context@ntg.nl> wrote:
> 
> about names:
> 
> how about
> 
> t-luageo.lmt
> t-luageo.mpxl
> 
> so that one knows what comes with the module (we do the same with s-* modules)

"t-luageo.lmt" is fine, but "t-luageo.mpxl" breaks the module. I think the line

\startMPdefinitions
   loadmodule "luageo" ;
\stopMPdefinitions

finds “mp-luageo” but not “t-luageo”. Changing the line to "loadmodule “t-luageo” does not work either.

> and you can add the example to the end of the module

Done.

> On Dec 18, 2023, at 3:08 AM, Hans Hagen via ntg-context <ntg-context@ntg.nl> wrote:
> 
>> Also, we do have a strange artifact, at least when I run this code. There is a line running across Brazil:
>> 
> i'm not sure where that comes from (you can try &&&)


I will use &&& in my upcoming module, t-discoworld.

[-- Attachment #2: luageoDisco.png --]
[-- Type: image/png, Size: 34829 bytes --]

[-- Attachment #3: Type: text/plain, Size: 163 bytes --]


(Drawn with eofill, for maximum grooviness.)

Is there a place I can read about disconnected paths, &&&&, and &&&? These are totally unfamiliar to me.

Gavin

[-- Attachment #4: Type: text/plain, Size: 511 bytes --]

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Hans Hagen via ntg-context]

On 12/18/2023 5:22 PM, Gavin wrote:
> Hi Hans,
> 
>> On Dec 18, 2023, at 3:12 AM, Hans Hagen via ntg-context <ntg-context@ntg.nl> wrote:
>>
>> about names:
>>
>> how about
>>
>> t-luageo.lmt
>> t-luageo.mpxl
>>
>> so that one knows what comes with the module (we do the same with s-* modules)
> 
> "t-luageo.lmt" is fine, but "t-luageo.mpxl" breaks the module. I think the line
> 
> \startMPdefinitions
>     loadmodule "luageo" ;
> \stopMPdefinitions
> 
> finds “mp-luageo” but not “t-luageo”. Changing the line to "loadmodule “t-luageo” does not work either.

so how about  mp-t-luageo

>> and you can add the example to the end of the module
> 
> Done.
> 
>> On Dec 18, 2023, at 3:08 AM, Hans Hagen via ntg-context <ntg-context@ntg.nl> wrote:
>>
>>> Also, we do have a strange artifact, at least when I run this code. There is a line running across Brazil:
>>>
>> i'm not sure where that comes from (you can try &&&)
> 
> 
> I will use &&& in my upcoming module, t-discoworld.
> 
> 
> 
> (Drawn with eofill, for maximum grooviness.)
> 
> Is there a place I can read about disconnected paths, &&&&, and &&&? These are totally unfamiliar to me.
at some point in the luametafun manual and they are probabaly mentioned 
in some docs that describe development

it's anyway something introduced last year, so kind of new

Hans

-----------------------------------------------------------------
                                           Hans Hagen | PRAGMA ADE
               Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
        tel: 038 477 53 69 | www.pragma-ade.nl | www.pragma-pod.nl
-----------------------------------------------------------------

___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Gavin via ntg-context]

Hi Hraban,

This was very helpful. I think I have everything organized according to TDS now.

> Have a look at
> https://wiki.contextgarden.net/Modules#Module_writing_guidelines
> … and please tell me, if you miss anything or find errors!

Regarding TDS, the wike page says:

> Sort these files into folders according to TDS (TeX directory structure) – just have a look at the distribution to understand what goes where.

This was a dead end for me. I didn’t know where to look, or what to look for. I recommend adding these items, modified from your email:

> – Module code and data files go into tex/context/third/luageo
> – Documentation files go into doc/context/third/luageo

Those instructions were very easy to follow. Maybe you need to elaborate for more general cases, but that was everything I needed to know about TDS.

Pointing to a specific example, as you did in the email, is also helpful.

> Also look at the structure of other modules in the distribution, or e.g.
> https://codeberg.org/fiee/context-simpleslides


I haven’t learned to make wiki contributions myself yet. It is nearing the top of my to-do list.

Thanks!
Gavin
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________

[NTG-context] Re: Seeking advice for module that draws globes

[Henning Hraban Ramm]

Am 19.12.23 um 15:27 schrieb Gavin via ntg-context:
> This was very helpful. I think I have everything organized according to TDS now.

Thank you for the feedback!

>> Sort these files into folders according to TDS (TeX directory structure) – just have a look at the distribution to understand what goes where.
> 
> This was a dead end for me. I didn’t know where to look, or what to look for. I recommend adding these items, modified from your email:
> 
>> – Module code and data files go into tex/context/third/luageo
>> – Documentation files go into doc/context/third/luageo
> 
> Those instructions were very easy to follow. Maybe you need to elaborate for more general cases, but that was everything I needed to know about TDS.
> 
> Pointing to a specific example, as you did in the email, is also helpful.
> 
>> Also look at the structure of other modules in the distribution, or e.g.
>> https://codeberg.org/fiee/context-simpleslides

Ok, I added that to the wiki page and fixed a few other things.


> I haven’t learned to make wiki contributions myself yet. It is nearing the top of my to-do list.

First create an account (link in the upper right corner). Anonymous 
editing is disabled due to spam.

You can create a new page just by calling it, e.g. 
https://wiki.contextgarden.net/My_new_page
and then click on "create this page".

Have a look at https://wiki.contextgarden.net/Wiki:Editing
The page links to general MediaWiki syntax but also explains the special 
formatting of our wiki.

Usually it makes sense to link _to_ your new page from a related 
(overview) page and _from_ your page back to that.

Command reference pages are special in that they read data from 
interface files and display a form to fill in explanations and examples.
(That doesn’t yet work with interface files of modules.)

Hraban
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / https://mailman.ntg.nl/mailman3/lists/ntg-context.ntg.nl
webpage  : https://www.pragma-ade.nl / https://context.aanhet.net (mirror)
archive  : https://github.com/contextgarden/context
wiki     : https://wiki.contextgarden.net
___________________________________________________________________________________