con.cor.dance

Declarative Deployment of OwnTracks Frontend with NixOS

2025-04-16T00:00:00-05:00

This a followup to my previous post about setting up OwnTracks on a home server running NixOS. One step of that process was to download the OwnTracks Frontend single page application zip archive and copy it into /var/www/html/owntracks to be served by Nginx. Now I'd like to look at replacing this procedure with a declarative approach by defining the resource in the server's configuration.nix.

An Aside: Google Drops the Ball

It turns out my concerns about Google's Map Timeline service were prescient. Last month, a "technical issue" resulted in the loss of users' Timeline data. Luckily, I had the back-up-to-cloud option turned on and was able to recover my Timeline history. Once I had done that, I exported the data from the app for safekeeping. At some point I might try converting and importing that data into OwnTracks.

Writing a Nix Derivation

The first step to the declarative deployment is to write a Nix derivation that packages the Frontend application. The principled thing to do would probably be referencing the source repo and building the application as part of the derivation. But since this is a Javascript project built using Vite, I was afraid doing that might be complicated. Also, I am primarily interested in a reproducible server deployment rather than the reproducibility of the package itself. By that logic I decided to base the derivation on the prebuilt artifact from the repo's releases.

Here the goal will be to write a owntracks-frontend.nix derivation and a default.nix to invoke it so that executing nix-build -A owntrack-frontend generates a result link to a Nix store path containing the contents of the OwnTracks Frontend package. To do this I followed the nix.dev tutorial on packaging existing software.

In the first iteration I created two files with the following contents.

# owntracks-frontend.nix
{
  stdenv,
  fetchzip
}:
stdenv.mkDerivation {
  pname = "owntracks-frontend";
  version = "v2.15.3";
  src = fetchzip {
    url = "https://github.com/owntracks/frontend/releases/download/v2.15.3/v2.15.3-dist.zip";
    sha256 = "";
  };
}

And,

# default.nix
let
  pkgs = import <nixpkgs> { config = {}; overlays = []; };
in
{
  owntracks-frontend = pkgs.callPackage ./owntracks-frontend.nix { };
}

Then executing nix-build -A owntracks-frontend produces the expected error regarding the incorrect hash.

error: hash mismatch in fixed-output derivation '/nix/store/im2lmhh4a2h7x87plz9i1fsc5fw8vhyf-source.drv':
         specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
            got:    sha256-iy+yISPcOD/2lTyJUb1eI3wufLku1mKfVDm0+Dy8OKk=
error: 1 dependencies of derivation '/nix/store/bm08ivlk0nqc61kz6vallfndbq2xn5ly-owntracks-frontend-v2.15.3.drv' failed to build

This error gives the correct hash so it can be put into the derivation.

  src = fetchzip {
    url = "https://github.com/owntracks/frontend/releases/download/v2.15.3/v2.15.3-dist.zip";
    sha256 = "iy+yISPcOD/2lTyJUb1eI3wufLku1mKfVDm0+Dy8OKk=";
  };

Now, Nix will accept the source, and the build proceeds up to the next error.

error: builder for
'/nix/store/csw1kq323p6lipcwbs9q109rf85vbx1n-owntracks-frontend-v2.15.3.drv'
failed to produce output path for output 'out' at 
'/nix/store/csw1kq323p6lipcwbs9q109rf85vbx1n-owntracks-frontend-v2.15.3.drv.chroot/root/nix/store/br9k7nxj067cmza64s5r92f2zchrj5vx-owntracks-frontend-v2.15.3'

This means that the derivation is not creating an output directory which should contain the result. That's because this package isn't a normal Autotools build. All that really needs to happen, with one caveat I'll get to, is to copy the files that were downloaded as the source into the output directory. That can be accomplished by overriding the install phase as described in the tutorial.

# owntracks-frontend.nix
{
  stdenv,
  fetchzip
}:
stdenv.mkDerivation {
  pname = "owntracks-frontend";
  version = "v2.15.3";
  src = fetchzip {
    url = "https://github.com/owntracks/frontend/releases/download/v2.15.3/v2.15.3-dist.zip";
    sha256 = "iy+yISPcOD/2lTyJUb1eI3wufLku1mKfVDm0+Dy8OKk=";
  };

  installPhase = ''
    runHook preInstall
    cp -r . $out
    runHook postInstall
  '';
}

Now, nix-build -A owntrack-frontend is able to succeed, and the result link points to a Nix store path containing the expected files.

$ nix-build -A owntracks-frontend
this derivation will be built:
  /nix/store/n07d9lsy8g4h8q7b69i51511ddfnqpq7-owntracks-frontend-v2.15.3.drv
building '/nix/store/n07d9lsy8g4h8q7b69i51511ddfnqpq7-owntracks-frontend-v2.15.3.drv'...
Running phase: unpackPhase
unpacking source archive /nix/store/nwca1gys4hl68cnslmiakcjaqkl8v612-source
source root is source
Running phase: patchPhase
Running phase: updateAutotoolsGnuConfigScriptsPhase
Running phase: configurePhase
no configure script, doing nothing
Running phase: buildPhase
no Makefile or custom buildPhase, doing nothing
Running phase: installPhase
Running phase: fixupPhase
shrinking RPATHs of ELF executables and libraries in /nix/store/4z9iardq8amf6f54azfznphy2dbb76fh-owntracks-frontend-v2.15.3
checking for references to /build/ in /nix/store/4z9iardq8amf6f54azfznphy2dbb76fh-owntracks-frontend-v2.15.3...
patching script interpreter paths in /nix/store/4z9iardq8amf6f54azfznphy2dbb76fh-owntracks-frontend-v2.15.3
/nix/store/4z9iardq8amf6f54azfznphy2dbb76fh-owntracks-frontend-v2.15.3

$ ls -lL result
total 60
dr-xr-xr-x 2 root root  4096 Dec 31  1969 assets
dr-xr-xr-x 2 root root  4096 Dec 31  1969 config
-r--r--r-- 1 root root  1150 Dec 31  1969 favicon.ico
-r--r--r-- 1 root root  3647 Dec 31  1969 icon-180x180.png
-r--r--r-- 1 root root   718 Dec 31  1969 index.html
-r--r--r-- 1 root root   377 Dec 31  1969 manifest.json
-r--r--r-- 1 root root 36117 Dec 31  1969 OwnTracks.svg

The caveat I mentioned is that the config directory needs to include a config.js file to set up the frontend app. As described in the previous post, for my purposes it needs to contain the following:

window.owntracks = window.owntracks || {};
window.owntracks.config = {
  api: {
    baseUrl: "http://wimpy.bleak-moth.ts.net:8083"
  },
  router: {
    basePath: "owntracks"
  }
};

This can be accomplished using the pkgs.writeText library function which puts some arbitrary text into a file in the Nix store. That file can then be referenced later in the derivation. So, I added such an attribute to the mkDerivation call and then, in the install phase, copied the generated file into the appropriate place in the $out directory. Notice, this entails adding writeText to the argument list of the function.

# owntracks-frontend.nix
{
  stdenv,
  writeText,
  fetchzip
}:
stdenv.mkDerivation {
  pname = "owntracks-frontend";
  version = "v2.15.3";
  src = fetchzip {
    url = "https://github.com/owntracks/frontend/releases/download/v2.15.3/v2.15.3-dist.zip";
    sha256 = "iy+yISPcOD/2lTyJUb1eI3wufLku1mKfVDm0+Dy8OKk=";
  };

  config = writeText "config.js" ''
    window.owntracks = window.owntracks || {};
    window.owntracks.config = {
      api: {
        baseUrl: "http://wimpy.bleak-moth.ts.net:8083"
      },
      router: {
        basePath: "owntracks"
      }
    };
  '';

  installPhase = ''
    runHook preInstall
    cp -r . $out
    cp $config $out/config/config.js
    runHook postInstall
  '';
}

Rebuilding the package and checking its contents shows the config.js file is present and has the right content.

$ nix-build -A owntracks-frontend
these 2 derivations will be built:
  /nix/store/dacc8ma93fl60qvp359nqb0b9liv5v57-config.js.drv
  /nix/store/adpvald53kxzhcfmm840xdvfydbn88yw-owntracks-frontend-v2.15.3.drv
.
.
.

/nix/store/dbml7xvlqv2lgcjfb3s0y17m5nj9bdmi-owntracks-frontend-v2.15.3

$ cat result/config/config.js 
window.owntracks = window.owntracks || {};
window.owntracks.config = {
  api: {
    baseUrl: "http://wimpy.bleak-moth.ts.net:8083"
  },
  router: {
    basePath: "owntracks"
  }
};

Making Use of the Derivation

At this point I'm able to build a directory in the Nix store which contains the SPA that I want to serve with Nginx. If done manually this would involve updating the Nginx configuration with a location block pointing to the path in the Nix store. Obviously, I want to accomplish this declaratively through configuration.nix in my NixOS server.

I wasn't immediately sure how to go about this. I knew that I could refer to derivations in pkgs using string interpolation and get the path to a package in the Nix store. I knew Nix would make sure the package was present in the store and build or download it if necessary. So if a pkgs.owntracks-frontend existed, I could do something like this:

  services.nginx = {
      enable = true;
      virtualHosts."wimpy" = {
        root = "/var/www/html";
        locations."/owntracks/" = {
          alias = "${pkgs.owntracks-frontend}/";
        };
      };
    };

Obviously, there is no pkgs.owntracks-fronted. But, I do now have owntracks-frontend.nix which contains a function that will produce the same kind of derivation as those in pkgs if invoked correctly. I reasoned that that is what default.nix is doing with the pkgs.callPackage invocation, and so maybe I could just do the same thing in my configuration.nix.

I copied owntracks-frontend.nix to be next to configuration.nix in my NixOS config repo and updated the latter with the following:

  services.nginx =
    let
      owntracks-frontend = pkgs.callPackage ./owntracks-frontend.nix { };
    in {
      enable = true;
      virtualHosts."wimpy" = {
        root = "/var/www/html";
        locations."/owntracks/" = {
          alias = "${owntracks-frontend}/";
        };
      };
    };

And, it worked!

Final Thoughts

I feel pretty happy with this accomplishment. It was really pretty simple, but I feel like I'm starting to get an inkling of how things in NixOS work.

One improvement that could be made, I think, is parameterizing the values in the config.js file. Right now the /owntracks/ base path is duplicated in the Nginx config and config.js. And surfacing the base URL for the API in the configuration.nix would also make more sense. Presumably, this could be accomplished by passing the values as parameters to the function in owntracks-frontend.nix. But I'll save that for later.

OwnTracks with NixOS and Tailscale

2025-02-21T00:00:00-06:00

In an effort to reduce my reliance on big tech I recently decided to try using OwnTracks to replace Google Maps Timeline. This article provides a rundown of how I accomplished this using an existing home server running NixOS and my existing Tailnet.

Background

For various reasons I find it useful to be able to review my past whereabouts, and Google Timeline has worked fairly well for this purpose. At some point Google changed Timeline to only store location history on the mobile device, removing it from the Maps web app. I've also found that the UI for Timeline on my phone has become laggy and feels like it could fail at any time. These seem like warning signs that Google may be neglecting the service or that it may be dropped entirely.

To hedge against that possibility and in furtherance of my general goal of reducing dependence on big tech, I've decided try replacing this service with OwnTracks.

OwnTracks

OwnTracks consists of a few components, including mobile apps for Android and iOS that send location updates to a server. The server can either be an MQTT broker or the OwnTracks Recorder. Using an MQTT broker permits live location sharing among devices running the app. Since I only care about recording my location history, I can forgo the MQTT broker and set up the app to publish updates directly to the recorder via HTTP.

The OwnTracks Recorder acts as a database to store location histories published by the mobile apps. It also provides APIs for querying the stored histories.

There is also an OwnTracks Frontend which provides a web app for viewing the stored location histories from the Recorder service.

Tailscale

Tailscale is a peer-to-peer VPN solution. Since I already have Tailscale set up on my home server and my phone, I can avoid a lot of fiddly work securing (in both senses of the word) a publicly available IP address for my server. As long as my phone is connected to my Tailscale VPN, known as a Tailnet, my phone can directly connect to the server.

Running the OwnTracks Recorder

I added a systemd service declaration to my NixOS configuration on my server to run the OwnTracks Recorder service. To avoid running the service with root privileges I'm using the dynamic user facility provided by systemd which automatically creates an unprivileged user to run the process. The StateDirectory directive causes a directory to be created under /var/lib with permissions allowing the service to store its persistent state (the location histories, in this case) across restarts.

Since OwnTracks Recorder has been packaged for NixOS I can reference the package directly to invoke the service, and Nix will automatically make sure it is installed. I'm using the unstable channel so the package includes a recent commit which fixes the HTTP mode for the service. This is necessary for the setup to work. The fix should be included in the next stable release of NixOS.

When the executable is invoked it is provided with the path to the dynamic user's state directory via the --storage flag. The --port 0 flag tells Recorder not to try to connect to an MQTT broker. I leave the HTTP port at the default 8083. Other command line options are in the documentation.

  systemd.services.owntracks = {
    enable = true;
    description = "owntracks recorder";
    serviceConfig = {
      ExecStart = ''
        ${pkgs.owntracks-recorder}/bin/ot-recorder \
           --storage /var/lib/owntracks/recorder/store \
           --port 0
        '';
      DynamicUser = true;
      StateDirectory = "owntracks";
      Restart = "always";
    };
    wantedBy = [ "multi-user.target" ];
  };

Running sudo nixos-rebuild switch will start the Recorder service. This can be verified by visiting the HTTP endpoint in a browser. Within my Tailnet my server is reachable at wimpy.bleak-moth.ts.net. Since the Recorder service is using its default port, I can confirm it is running and available from my Tailscale connected laptop or phone by visiting http://wimpy.bleak-moth.ts.net:8083. There I will see the minimal web page the server provides:

Setting Up the Mobile App

The OwnTracks mobile app can be installed from the Google or Apple app stores. It needs to be configured to send updates to the recorder by setting the Mode and Endpoint URL values in the app's Preferences -> Connection menu. The mode is set to HTTP since I'm not using MQTT. The endpoint URL is set to http://wimpy.bleak-moth.ts.net:8083/pub. This is my server's FQDN plus the path for publishing updates. I was stuck for awhile due to not knowing the /pub path was required.

As seen above, the Connection settings also include Identification and Credentials sections. Since the VPN prevents anyone else from accessing the server, I am not setting up any sort of access control in the OwnTracks system. Thus the credentials do not need to be set, but it is worth setting a user name so that the stored location history will be recorded under that name. This name will then appear on the maps. Likewise, the values for Device ID and Tracker ID.

With the Connection settings configured, the mobile app should start sending location updates to the server. Updates can be manually pushed by clicking on the upload button in the map header of the app's main view.

I'm able to confirm the server is receiving location updates by checking the logs for the OwnTracks Recorder service. Notice the POST requests to the /pub endpoint. These correspond to pushing the upload button in the app on my phone.

I can also check that locations have been uploaded by opening the location table link from the server's main web page.

For troubleshooting purposes, the mobile app provides a Status menu with useful information including logs. I found it helpful in getting the connection established. I think the logs were what clued me into the /pub path.

Setting Up the Frontend

Once I had my location updates being recorded, it was time to set up the frontend so that I could view the history. The OwnTracks Frontend is a single page application that can be served from any webserver. Since I already had Nginx running and serving static pages out of /var/www/html/, it was pretty easy.

The README offers instructions to either use Docker or build the app manually, but I just download the zip archive from the repo's releases page. Inside, in typical NPM package fashion, is a dist directory. I copied the contents to /var/www/html/owntracks.

The app is configured by copying the config/config.example.js file to config/config.js and making edits there. For this setup I needed to set two values. The api.baseURL for the OwnTracks Recorder's API is set to http://wimpy.bleak-moth.ts.net:8083. And router.basePath is set to owntracks since I'm hosting the app under that path. If router.basePath is not set correctly, the app will load but not display the map.

// Here you can overwite the default configuration values
window.owntracks = window.owntracks || {};
window.owntracks.config = {
    api: {
        baseUrl: "http://wimpy.bleak-moth.ts.net:8083"
    },
    router: {
        basePath: "owntracks"
    }
};

The working frontend looks like the image below and provides options to view location history for past date-time ranges and with options for points, lines, and a heatmap. Here I have zoomed the map way out to avoid advertising my exact location to the Internet.

My use case mostly involves viewing location histories for specific days. At first I was confused by the UI for selecting dates. The trick is that you have to select the date range by clicking on the start day in the calendar and then the end day. If you want just a single day, you have to click on that day twice.

Conclusion

At this point I have a setup which seems to be working well enough for my purposes. I've been using it for a few weeks, and I'm able to look back over my history to see where I was at particular times. There are a couple of things I would still like to do. First, it seems like I should be able to write an ad-hoc Nix derivation for the OwnTracks Frontend so that I can include it declaratively in my NixOS configuration. This would be preferable to manually downloading and copying the distribution. Secondly, I'd like my data to be backed up. I think this should be as simple as setting up Borg and pointing it at the OwnTracks Recorder's state directory.

Z3bra Puzzle

2024-06-06T00:00:00-05:00

I occasionally encounter problems akin to logic grid puzzles in programming challenges or other contexts. I usually approach them through some ad hoc backtracking algorithm. Recently I decided to try and develop a systematic approach for solving such problems without reinventing the wheel each time.

These puzzles fall into the category of constraint satisfaction problems. I knew that tools like the SMT solver, Z3, could be used to solve such problems, but it wasn't immediately obvious to me how to go about it.

I encountered some difficulty finding examples or tutorials on this. But, I did find this post by David Cook which, along with the associated code, was very helpful in getting started.

Background

First of all, what are the characteristics of logic grid puzzles, and how can they be described in a way that facilitates a systematic approach to solving them?

Broadly speaking, a logic grid puzzle can be characterized as a set of dimensions, each of which has a number of discreet values. If the puzzle is solvable, there are unique correspondences between the values of each of the dimensions. The goal is to explicitly determine the correspondences given a list of clues amounting to assertions that most hold.

The pen and paper approach involves representing the puzzle as a grid and proceeds by marking correspondences as either established or excluded using check marks and cross marks. For an SMT solution, a means of encoding the puzzle using the abstractions provided by the SMT solver must be sought.

The Zebra Puzzle

A classic example of this sort of puzzle is the Zebra Puzzle. Quoting from the Wikipedia article:

The following version of the puzzle appeared in Life International in 1962:

There are five houses.

The Englishman lives in the red house.

The Spaniard owns the dog.

Coffee is drunk in the green house.

The Ukrainian drinks tea.

The green house is immediately to the right of the ivory house.

The Old Gold smoker owns snails.

Kools are smoked in the yellow house.

Milk is drunk in the middle house.

The Norwegian lives in the first house.

The man who smokes Chesterfields lives in the house next to the man with the fox.

Kools are smoked in the house next to the house where the horse is kept.

The Lucky Strike smoker drinks orange juice.

The Japanese smokes Parliaments.

The Norwegian lives next to the blue house.

Now, who drinks water? Who owns the zebra?

In the interest of clarity, it must be added that each of the five houses is painted a different color, and their inhabitants are of different national extractions, own different pets, drink different beverages and smoke different brands of American cigarets [sic]. One other thing: in statement 6, right means your right.

Z3 Sorts

In this puzzle there are five dimensions. The colors of the houses, the nationality of their inhabitants, the species of pets in the houses, and the beverage and cigarette preferences of the inhabitants. In Python Z3 each of these dimensions can be expressed as an EnumSort.

House, (red_house, green_house, ivory_house, yellow_house, blue_house) = \
    EnumSort("House", "red green ivory yellow blue".split())

Nation, (england, spain, ukraine, norway, japan) = \
    EnumSort("Nation", "england spain ukraine norway japan".split())

Beverage, (coffee, tea, milk, juice, water) = \
    EnumSort("Drink", "coffee tea milk juice water".split())

Pet, (dog, snails, fox, horse, zebra) = \
    EnumSort("Pet", "dog snails fox horse zebra".split())

Smoke, (oldgold, kools, chesterfields, luckystrikes, parliaments) = \
    EnumSort("Smoke", "oldgold kools chesterfields luckystrikes parliaments".split())

An EnumSort defines a new Z3 sort, similar to a type, consisting of the specific given values and returns references to the sort itself and constants for each of the values. The arguments are the name of the sort in Z3 and the names of the values.

Z3 Function Declarations

The puzzle makes clear that correspondences amongst the dimensions are all one-to-one.

In the interest of clarity, it must be added that each of the five houses is painted a different color, and their inhabitants are of different national extractions, own different pets, drink different beverages and smoke different brands of American cigarets [sic].

This means any of the dimensions could be thought of as a function of any of the others. For this approach, however, it is useful to pick one dimension as an independent variable and treat the other dimensions as dependent variables that are functions of it.

Many of the clues are stated in terms of the color of the houses, so I'll use that as the independent variable. That's why I've used colors as the values of the House sort. For each of the other dimensions, a function is declared from the House sort to the sort corresponding to that dimension. The Function constructor takes the name of the function, the domain sort, and the codomain sort as arguments.

nationality = Function("nationality", House, Nation)

drinks = Function("drinks", House, Beverage)

pet = Function("pet", House, Pet)

smokes = Function("smokes", House, Smoke)

Some of the clues involve the ordering of the houses. This is handled by declaring a function from the House sort to the integers, IntSort.

house_number = Function("house_number", House, IntSort())

Constraints

With the sorts and functions declared, the constraints of the problem can be added as assertions. This is done by creating a Solver instance and using the add method which can accept multiple assertions as arguments.

solver = Solver()
solver.add(...)

The constraints will come from the clues and from the requirement that the functions be one-to-one. To start with a simple assertion, clue 2 states, "The Englishman lives in the red house." This can be directly translated into a Z3 constraint by asserting that the nationality function evaluated at the red_house value of the House sort must give the england value of the Nation sort.

solver.add(
    # 2. The Englishman lives in the red house.
    nationality(red_house) == england
)

Clues 4 and 8 are also straightforward since they involve statements about specific colors of houses, the independent variable.

solver.add(
    # 4. Coffee is drunk in the green house.
    drinks(green_house) == coffee,

    # 8. Kools are smoked in the yellow house.
    smokes(yellow_house) == kools,
)

Relationships between two dependent variables

When a clue involves a relationship between two dependent variables, the situation is a bit more complicated. Clue 3, "The Spaniard owns the dog," is an example. There is no function from Nation to Pet or vice-versa to characterize this statement. Nor is there is an inverse from either to the independent variable that would permit pet(nationality_inverse(spain)) == dog. Instead, a universal quantifier can be used to introduce a variable, h, of the House sort. Now it can be asserted that anytime nationality(h) is spain, pet(h) must be dog.

The universal quantifier takes the form ForAll(vars, assertion), where vars can be single variable or a list of variables. Owing to how the language is represented in Python, each variable has to be represented using a predefined constant to specify the sort. This is a bit confusing since the variable inside the quantifier bears no relationship to the constant other than the sort. With this in mind, clue 3 can be encoded as follows:

h = Const('h', House) # A dummy constant.
solver.add(
    # 3. The Spaniard owns the dog.
    ForAll(h, (nationality(h) == spain) == (pet(h) == dog))
)

The expressions nationality(h) == spain and pet(h) == dog both evaluate to values of BoolSort, either true or false. By equating them, the quantifier requires both to evaluate to the same truth value for a given h. Meaning, for any given house "the occupant is Spanish" is equivalent to "the house has a dog". For clarity I think it is worth defining a helper function for logical equivalence.

def Iff(a, b):
    return a == b

This provides a nice parallel with the provided Implies function that will be used later. With the ForAll and Iff functions, clues 3, 5, 7, 13, and 14 can be encoded.

h = Const('h', House) # A dummy constant.
solver.add(
    # 3. The Spaniard owns the dog.
    ForAll(h, Iff(nationality(h) == spain, pet(h) == dog)),

    # 5. The Ukrainian drinks tea.
    ForAll(h, Iff(nationality(h) == ukraine, drinks(h) == tea)),

    # 7. The Old Gold smoker owns snails.
    ForAll(h, Iff(smokes(h) == oldgold, pet(h) == snails)),

    # 13. The Lucky Strike smoker drinks orange juice.
    ForAll(h, Iff(smokes(h) == luckystrikes, drinks(h) == juice)),

    # 14. The Japanese smokes Parliaments.
    ForAll(h, Iff(nationality(h) == japan, smokes(h) == parliaments)),
)

Note that the same dummy constant h can be used in all of the assertions.

The function house_number has been declared from houses to integers, but it is under specified. If the houses are numbered from one to five, left to right, clues 1, 6, 9, and 10 can be formulated.

solver.add(
    # 1. There are five houses.
    ForAll(h, And(house_number(h) >= 1, house_number(h) <= 5)),

    # 6. The green house is immediately to the right of the ivory house.
    house_number(green_house) == house_number(ivory_house) + 1,

    # 9. Milk is drunk in the middle house.
    ForAll(h, Iff(house_number(h) == 3, drinks(h) == milk)),

    # 10. The Norwegian lives in the first house.
    ForAll(h, Iff(nationality(h) == norway, house_number(h) == 1)),
)

The assertion for the first rule is really requiring the house numbers to go from 1 to 5. The definition of the House sort already fixed the cardinality at five.

Constraints involving two variables

Clue 11 states, "The man who smokes Chesterfields lives in the house next to the man with the fox." This is a statement about two houses neither specified in terms of the independent variable, color. This can be handled by using a universal quantifier over two house variables, h and g, with predicates smokes(h) == chesterfields and pet(g) == fox. When the predicates hold, the houses must have consecutive house numbers.

h, g = Consts('h g')

def next_to(h, g):
    return Or(
        house_number(h) == house_number(g) + 1,
        house_number(h) == house_number(g) - 1,
    )

solver.add(
    # 11. The man who smokes Chesterfields lives in the house next
    # to the man with the fox.
    ForAll([h, g], Implies(
        And(smokes(h) == chesterfields, pet(g) == fox),
        next_to(h, g)
    )),
)

Here Implies is used instead of Iff since the implication is in one direction only. Two houses may be next to each other without the two predicates holding.

Clues 12 and 15 are handled similarly.

solver.add(
    # 12. Kools are smoked in the house next to the house where the horse is kept.
    ForAll([h, g], Implies(
        And(smokes(h) == kools, pet(g) == horse),
        next_to(h, g)
    )),

    # 15. The Norwegian lives next to the blue house.
    ForAll(h, Implies(
        nationality(h) == norway,
        next_to(h, blue_house)
    )),
)

Bijectivity constraints

Finally, constraints need to be added regarding the one-to-one correspondence amongst all the dimensions. This requires all of the functions house_number, nationality, pet, drinks, and smokes to be injective. Given any two houses, h and g, if they are distinct, their images under each of the functions must be distinct. Because the house color has been used as the independent variable, it doesn't appear in the expression. Instead there is a requirement that the house numbers be distinct.

solver.add(
    # In the interest of clarity, it must be added that each of the five
    # houses is painted a different color, and their inhabitants are of
    # different national extractions, own different pets, drink different
    # beverages and smoke different brands of American cigarets [sic].
    ForAll([h, g], Implies(
        h != g,
        And(
            house_number(h) != house_number(g),
            nationality(h) != nationality(g),
            pet(h) != pet(g),
            drinks(h) != drinks(g),
            smokes(h) != smokes(g),
        )
    ))
)

Solution

With all of the constraints added to the solver, the satisfiability of the system can be checked. If the system can be satisfied, the solver can provide a model which does so.

assert solver.check() == sat

model = solver.model()

Such a model provides explicit definitions of all the declared functions and can evaluate arbitrary expressions.

In [1]: model.eval(house_number(red_house))
Out[1]: 3

In [2]: model.eval(smokes(ivory_house))
Out[2]: luckystrikes

The puzzle asks, "who drinks water? Who owns the zebra?" These questions can be answered by declaring two constants of the House sort which are constrained to meet the two predicates.

# Now, who drinks water? Who owns the zebra?

the_water_house = Const("the_water_house", House)
the_zebra_house = Const("the_zebra_house", House)

solver.add(
    drinks(the_water_house) == water,
    pet(the_zebra_house) == zebra
)

assert solver.check() == sat

model = solver.model()

The resulting model can then return explicit values for the two constants.

In [3]: model.eval(the_water_house)
Out[3]: yellow

In [4]: model.eval(the_zebra_house)
Out[4]: green

If "who" means the nationality of the inhabitants, that can be answered, too.

In [5]: model.eval(nationality(the_water_house))
Out[5]: norway

In [6]: model.eval(nationality(the_zebra_house))
Out[6]: japan

The Norwegian drinks the water, and the person with the zebra is Japanese.

Code

The full code for this example can be found in my github repository which also contains other examples and approaches.

Rocks and Hailstones

2024-03-22T00:00:00-05:00

I had fun solving the second part of Day 24 of Advent of Code this year. This was a more mathematical problem than most, and by working with vectors and matrices it can be solved with minimal faffing about at the component level.

We are given a set of initial positions and velocities for a number, $n> 3$, of hailstones. The hailstones travel in straight lines at constant velocities, and we are asked to find the initial position and velocity of rock thrown so that it will impact (without then changing its velocity) all of the given hailstones. We are told the the paths of the hailstones are such that this is possible.

Let $\vec{r}_i$ and $\vec{v}_i$ represent the initial position and velocity vectors of the $i$th hailstone. These are given. Let $\vec{s}$ and $\vec{u}$ represent the initial position and velocity vectors of the thrown rock. These are the unknowns we are solving for. If the thrown rock impacts the $i$th hailstone at time $t_i$, their positions at that time must be the same.

$$ \vec{u} t_i + \vec{s} = \vec{v}_i t_i + \vec{r}_i $$

$$ (\vec{u} - \vec{v}_i)t_i = \vec{r}_i - \vec{s} $$

Remembering that the cross product of parallel vectors is zero, we can eliminate $t_i$, which is an unknown we don't care about, by taking the cross product of both sides with $(\vec{u} - \vec{v}_i)$.

$$ (\vec{u} - \vec{v}_i)\times(\vec{u} - \vec{v}_i)t_i = (\vec{u} - \vec{v}_i)\times(\vec{r}_i - \vec{s}) $$

$$ \vec{0} = (\vec{u} - \vec{v}_i)\times(\vec{r}_i - \vec{s}) $$

Geometrically, this is saying the velocity of the thrown rock must be parallel to the vector between its initial position and that of the hailstone. This makes sense. We proceed by expanding out the multiplication.

$$ \vec{0} = \vec{u} \times \vec{r}_i - \vec{u} \times \vec{s} - \vec{v}_i \times \vec{r}_i + \vec{v}_i \times \vec{s} $$

The terms $\vec{u} \times \vec{r}_i$ and $\vec{v}_i \times \vec{s}$ are linear in the unknowns and unproblematic. The term $\vec{v}_i \times \vec{r}_i$ is a constant formed from the givens. In contrast, $\vec{u} \times \vec{s}$ represents products among the unknowns and would prevent solution by standard methods for systems of linear equations. On the other hand, this term only includes properties of the thrown rock. This means it is independent of the impacted hailstone $i$ since all hailstones are struck by the same rock. The choice of the $i$th hailstone in obtaining the above equation was arbitrary. We can chose a different hailstone $j \ne i$ and get the same equation with the $i$ subscripts replaced with $j$. Subtracting the two equations will then eliminate the quadratic $\vec{u} \times \vec{s}$ term.

$$ \begin{align} \vec{u} \times \vec{r}_i - \vec{u} \times \vec{s} - \vec{v}_i \times \vec{r}_i + \vec{v}_i \times \vec{s} &=&\vec{0} \\ \vec{u} \times \vec{r}_j - \vec{u} \times \vec{s} - \vec{v}_j \times \vec{r}_j + \vec{v}_j \times \vec{s} &=&\vec{0} \\ \hline \\ \vec{u} \times (\vec{r}_i - \vec{r}_j) - \vec{v}_i \times \vec{r}_i + \vec{v}_j \times \vec{r}_j + (\vec{v}_i - \vec{v}_j) \times \vec{s} &=&\vec{0} \end{align} $$

We rearrange the resulting equation by moving the constant terms to the right hand side and reversing the cross product involving $\vec{u}$. Reversing the cross product introduces a minus sign which we absorb by reversing the subtraction in $(\vec{r}_i - \vec{r}_j)$.

$$ (\vec{v}_i - \vec{v}_j) \times \vec{s} + (\vec{r}_j - \vec{r}_i) \times \vec{u} = \vec{v}_i \times \vec{r}_i - \vec{v}_j \times \vec{r}_j $$

This is a system of three linear equations with six unknowns. Another three equations are required to fully determine the solution. These can be obtained by replacing the arbitrary choice of the $j$th hailstone with a third hailstone $k$ distinct from both $j$ and $i$ to yield a new, independent vector equation.

$$ (\vec{v}_i - \vec{v}_k) \times \vec{s} + (\vec{r}_k - \vec{r}_i) \times \vec{u} = \vec{v}_i \times \vec{r}_i - \vec{v}_k \times \vec{r}_k $$

To solve this linear system we need to translate the two vector equations into one six dimensional matrix equation of the form $\boldsymbol{Mx}=\boldsymbol{b}$.

The cross products can be represented in matrix form, $\vec{a}\times\vec{b} = [\vec{a}]_\times\boldsymbol{b}$ where $\boldsymbol{b}$ is $\vec{b}$ as a column vector and the matrix $[\vec{a}]_\times$ is defined as

$$ [\vec{a}]_{\times} \stackrel{\rm def}{=} \begin{bmatrix}\,\,0&\!-a_3&\,\,\,a_2\\\,\,\,a_3&0&\!-a_1\\\!-a_2&\,\,a_1&\,\,0\end{bmatrix} $$

with $[a_1\, a_2\, a_3]^T = \boldsymbol{a}$ being the components of $\vec{a}$.

With this replacement the equations will take the forms

$$ [\vec{v}_i - \vec{v}_j]_\times \boldsymbol{s} + [\vec{r}_j - \vec{r}_i]_\times \boldsymbol{u} = [\vec{v}_i]_\times \boldsymbol{r}_i - [\vec{v}_j]_\times \boldsymbol{r}_j $$

and

$$ [\vec{v}_i - \vec{v}_k]_\times \boldsymbol{s} + [\vec{r}_k - \vec{r}_i]_\times \boldsymbol{u} = [\vec{v}_i]_\times \boldsymbol{r}_i - [\vec{v}_k]_\times \boldsymbol{r}_k. $$

We'll also need to represent all six unknowns in one column vector $\boldsymbol{x}$ which we can define by stacking $\boldsymbol{s}$ atop $\boldsymbol{u}$.

$$\boldsymbol{x} \stackrel{\rm def}{=} \begin{bmatrix}s_1\\ s_2\\ s_3\\ u_1\\ u_2\\ u_3\end{bmatrix}$$

Now the system of equations can be written using block matrices as

$$ \left[\begin{array}{@{}c|c@{}} [\vec{v}_i - \vec{v}_j]_\times & [\vec{r}_j - \vec{r}_i]_\times \\\hline [\vec{v}_i - \vec{v}_k]_\times & [\vec{r}_k - \vec{r}_i]_\times \\ \end{array}\right]\boldsymbol{x} = \begin{bmatrix} [\vec{v}_i]_\times \boldsymbol{r}_i - [\vec{v}_j]_\times \boldsymbol{r}_j \\\hline [\vec{v}_i]_\times \boldsymbol{r}_i - [\vec{v}_k]_\times \boldsymbol{r}_k \end{bmatrix}. $$

This is a six dimensional system of equations where the left hand side consists of a $6\times6$ square matrix $\boldsymbol{M}$ times our six component column vector of unknowns, and the right hand side is a $6\times1$ column vector $\boldsymbol{b}$. This system can be solved using standard methods such as Gaussian elimination. To compute $\boldsymbol{M}$ and $\boldsymbol{b}$, we just need functions for the cross product matrix $[\vec{v}]_\times$, for the multiplication of a vector by a matrix, for subtracting two vectors, and for joining matrices horizontally and vertically into block matrices.

I had hoped to use the Haskell hmatrix package since it includes the necessary functions except for $[\vec{a}]_\times$ and has a solve function for linear systems. Unfortunately it doesn't support arbitrary precision rational numbers which is required to produce the exact answer called for by AoC. I ended up writing my own implementation of the functions and adapted a Guassian elimination routine from https://haskellicious.wordpress.com/2012/11/26/the-gauss-algorithm-in-haskell/. I won't include or discuss the code here since I just wanted to highlight the mathematical aspects. The interested reader can find the code in my Advent of Code solutions repository.

Migrating the Specify 6 SVN Repository to Git

2017-10-30T12:49:25-05:00

Until now the Specify 6 source code has been version controlled using Subversion. The decision was made to migrate the repository to Git. Here are some notes about how this was accomplished.

First Step: git-svn

The rough draft of the migration was obtained using the git-svn tool. One can find plenty of material about its use, so I will mostly just describe the particular choices I made as a sort of case study.

Making the authors.txt file

Because SVN commits are labeled by SVN user names while Git uses email addresses, git-svn accepts a mapping file that it uses to determine the author of the commits as they are replayed into the Git repository. The SVN user names can be easily obtained from the log.

svn log -q \
   | grep -e '^r' \
   | awk 'BEGIN { FS = "|" }; { print $2 }' \
   | sort -u \
   > authors.txt

In the resulting authors.txt file each user name will need to have its corresponding email addresses added. In the case of Specify there were several authors listed multiple times under different user names. This means that same email was sometimes added on multiple lines. The mapping need not be injective.

The effort to define the mapping is worthwhile, particularly when the resulting repository will be pushed GitHub. Having the real email addresses means contributors will be correctly attributed.

An interesting aspect of this process is determining the identities of past contributors given only the SVN user. My approach was searching through the project mailing list archive. Everyone who has worked on the project used it at some point, and it records their real names and email addresses.

Branches and Tags

It is possible to point git-svn to the tags and branches directories of an SVN repository and have it try to recapitulate the branch and merge history in Git. I made an initial attempt at using this capability, but it didn't seem to work on the first try. I decided that since we haven't been using SVN branches for the past few years, I wouldn't bother with trying to preserve them. From a preservation perspective it makes more sense to archive the SVN repository as a primary source rather than worrying about producing exact fidelity in a derivative artifact that's primary use is day-to-day development work.

With the completed authors.txt file in hand, a simple migration of the SVN trunk into Git is straightforward.

git-svn clone --prefix=svn/ --trunk=trunk/Specify \
   --authors-file=authors.txt \
   https://svn.code.sf.net/p/specify/code \
   specify2git

I don't remember exactly how long it took for git-svn to replay the roughly 12,000 commits into the new Git repository. Perhaps an hour. Too long to sit and watch, but not agonizingly slow, either.

Rewriting History

The resulting Git repository was approximately 600MB. A lot of the bulk comes from the project dependencies that are included in the repository as JAR files. This is not an ideal situation, but it is what it is. I briefly investigated some sort of git-annex solution to separate the libraries, but decided to take things one step at a time.

Still, I wanted to see what were the worst offenders in terms of file size. Perhaps I would learn something that would produce an easy win for reducing the bloat. Some Googling led me to a StackOverflow answer for finding the largest objects in a Git repository.

git rev-list --objects --all \
   | git cat-file \
      --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
   | grep '^blob' \
   | sort --numeric-sort --key=3

Sure enough, the largest object was an SQL file containing test data that had been removed at some point in the past. It was over 170MB. I was pretty sure it could be safely removed from the project history, but I wanted to see why it was there and when it had gone away.

You can see the history of deleted files using git log, but you have to say git log -- path/to/deleted/file or else Git will think the file path is the name of a branch or something.

In this case there were only two commits that touched the file. The one that added it and the immediate successor with the message "Accidently checked in." No doubt, then. I could remove this file from the history and immediately reduce the size of the repository by nearly 30%.

I've previously used git rebase to rewrite history, but I was aware there were better options for these kind of bulk operations. This time Google turned up an excellent post from Manish Goregaokar, Understanding Git filter-branch and the Git Storage Model. I was quickly able to figure out how to excise the file.

git filter-branch -f --prune-empty --index-filter \
   'git rm --cached --ignore-unmatch path/to/file' HEAD

The operation took about five minutes to complete.

Emboldened by this success, I returned to the list of large files in search of more bloat. I was able to eliminate a few large demo files. I also found instances where whole subdirectories had been accidentally committed. In one, someone had committed the actual installation directory into the repository, including an embedded MySQL database! In another, the entire source code repository had been added as a subdirectory of itself. The latter didn't add much to the size since Git only stores a single copy of identical files. Nevertheless, I removed it just the same.

Besides new files, some of these accidental commits also included other changes that were reverted by a subsequent commit. I removed these pairs of commits using git rebase -i on branches I created pointing to the reverting commit. I then used git rebase --onto to rewrite the later history onto those branches.

If I ever do something like this again, I should remember to search the commit logs for "accident*" and similar messages.

The Result

After all of this, the Git repository ended up being about 350MB according to du -h .git/objects/. Because Git retains old references when using filter-branch and rebase, the size reduction is not immediately apparent even after running git gc. The easiest way to get an accurate measurement is to make a new clone of the repository using git clone file://path/to/cleaned/up/repository new-clone. Only the objects actually reachable from HEAD will be brought over, but it is necessary to use the file:// style URI. Cloning the directory directly will only create hard links.

Using Leaflet maps in an Elm app

2017-08-30T00:00:00-05:00

I recently started a project creating a web app that requires displaying maps. This was to be a browser based app, but I wanted to use something safer and more maintainable than Javascript. I decided to give Elm a try and have been fairly happy with it. However, I couldn't find any pure Elm libraries for displaying maps that supported WMS layers and other features that would be needed.

So, the question became whether it would be possible to use a Javascript mapping library with my Elm application. It turns out that it is not too difficult to get basic rendering of maps to work using the Leaflet library. That will be the subject of this post.

In the future, I will attempt to add more advanced features such as selecting regions within a displayed map.

Paradigm conflict

The main difficulty with using Elm and Leaflet together is that Elm is totally based on the reactive paradigm where the entire state of your app is captured in a single immutable data structure from which the DOM is derived via a pure view function. Any change in what the user sees has to be accomplished by updating the state (Model in Elm parlance) in some way and allowing the DOM to be recomputed. This way of doing things and the resulting program structure are called The Elm Architecture, or TEA.

Behind the scenes the view function actually generates virtual DOM structures which are diffed to compute mutations to the real DOM. This is so that minor changes don't cause the whole page to be redrawn. However, this mechanism is not visible to the application programmer.

On the other hand, Leaflet and similar Javascript map libraries make use of mutation and side effects with full abandon. The DOM is treated as a persistent mutable object within which div elements may have a map objects attached. The map object then provides methods such as setView or addLayer that mutate the state of the map and update the DOM to effect the change.

Elm interop with Javascript

The primary means of interoperating with external Javascript in Elm is through ports. These allow incoming messages to be subscribed to, and outgoing messages to be dispatched. Incoming messages result in calls to a model update function when received. Outgoing messages can be generated upon model updates.

My initial approach was to use this port system to send messages out to Javascript for actions like: add a map to the div with id foobar, remove the map from the div, add this WMS layer. I managed to get this scheme to work, but it was complicated and seemed contrary to TEA. I was essentially maintaining program state in two separate locations, the Elm model and the Leaflet interface, and shuttling messages back and forth to keep them in sync.

What I really wanted was something like the way regular HTML is rendered in Elm, where the map could just be computed purely from the model.

Enter mutation observers

Ideally, it would be possible to tie-in to or extend the Elm virtual DOM system. There is an undocumented Elm feature called Native Modules that might make that possible, but I haven't investigated that very much.

Instead, I have currently settled on a solution that involves adding a HTML5 data attribute with the map state to the to-be Leaflet container divs. These divs are also given the class leaflet-map.

view : List WMSInfo -> Html msg
view wmsInfo =
    div
        [ class "leaflet-map"
        , attribute "data-leaflet" (serialize wmsInfo)
        ]
        []

Currently, the only map state I care about is a list of WMS layers to add to the map. The serialize function just makes JSON out of the layer information.

import Json.Encode exposing (..)


type alias WMSInfo =
    { mapName : String
    , layers : List String
    , endPoint : String
    }


serialize : List WMSInfo -> String
serialize =
    List.map
        (\info ->
            object
                [ ( "mapName", string info.mapName )
                , ( "endPoint", string info.endPoint )
                , ( "layers", info.layers |> List.map string |> list )
                ]
        )
        >> list
        >> encode 0

Now, on the Javascript side I can watch for mutations to the DOM involving elements with the leaflet-map class and invoke the necessary Leaflet methods to match the state in the data attribute. The relevant DOM mutations are when elements with the leaf-map class are added or removed anywhere in the page body and when the data-leaflet attribute changes on any element.

There is a Web API for doing such things called MutationObserver. The way it is used is to create an observer instance with a callback function that receives mutation events, and then activate the observer with some filters about what kinds of mutations to look for.

var observer = new MutationObserver(processMutations);

observer.observe(document.body, {
    subtree: true,
    childList: true,
    attributes: true,
    attributeFilter: ["data-leaflet"]
});

The subtree flag means to watch for mutations anywhere in the descendants of the observed element, which is the entire page body in this case. The childList flag will catch additions or removals of elements. The attributes flag indicates that changes to element attributes are of interest, but the attributeFilter allows the parameter allows that observation to be limited to only the data-leaflet attribute that contains the map information.

Mutating the map

Using this mechanism to observe relevant mutations to the DOM, the corresponding calls to the Leaflet library can be made to make it match the desired state.

function processMutations(mutations) {
    mutations.forEach(function(m) {
        processAddedNodes(m.addedNodes);
        processRemovedNodes(m.removedNodes);

        if (m.type == "attributes") {
            updateMap(m.target);
        }
    });
}

The mutation observer invokes its callback with a list of mutations. Each mutation object has a list added and a list of removed child nodes, either of which may be empty if there was nothing added or removed. There is also a type attribute that indicates the type of mutation. Since there is only one attribute that matches the attribute filter, any mutation of the type "attributes" means the element that was mutated, which is m.target, is a map container div that needs its map to be updated.

Taking added nodes first, each added node is examined for any elements with the class leaflet-map, because the added node may contain an entire subtree with multiple maps. For each matching element, the Leaflet map constructor is invoked. Leaflet set an undocumented attribute, _leaflet_id, on the container element. This unique id is used as the key in a global dictionary, called maps, where the Leaflet map object will be stored for later access. Finally, updateMap is called that to handle setting the map state, which will be explained subsequently.

function processAddedNodes(addedNodes) {
  addedNodes.forEach(function(n) {
      if (n.getElementsByClassName == null) return;

      var elements = n.getElementsByClassName("leaflet-map");
      Array.prototype.forEach.call(elements, function(element) {
          var map = L.map(element, {crs: L.CRS.EPSG4326}).setView([0, 0], 1);
          maps[element._leaflet_id] = map;  
          console.log("added leaflet id", element._leaflet_id);
          updateMap(element);
      });
  });
}

If a map is added or the data-leaflet attribute is changed, the map needs to be updated with current state. The Leaflet map object instance is obtained from the global maps dictionary according to the _leaflet_id attribute mentioned above. A separate global mapLayers dictionary keeps track of the layers that have been added to the map. To accomplish the update, all existing layers are first removed. Then, the JSON data that was stored in data-leaflet attribute needs to obtained. It will be contained in the HTMLElement dataset property, element.dataset.leaflet. This is the JSON data serialized from the Elm application. It is parsed and used to add layers to map. Each created layer object is added to the mapLayers global so they can be accessed later.

function updateMap(element) {
    var map = maps[element._leaflet_id];
    if (map == null) return;
    console.log("updating leaflet id", element._leaflet_id);

    var layers = mapLayers[element._leaflet_id];
    if (layers != null) {
        layers.forEach(function(layer) {  map.removeLayer(layer); });
    }

    var wmsInfos = JSON.parse(element.dataset.leaflet);

    mapLayers[element._leaflet_id] = wmsInfos.map(function(wmsInfo) {
        return L.tileLayer.wms(wmsInfo.endPoint, {
            mapName: wmsInfo.mapName,
            format: 'image/png',
            version: '1.1.0',
            transparent: true,
            layers: wmsInfo.layers.join(',')
        }).addTo(map);
    });
}

When nodes are removed, the node's descendants are again searched for the leaflet-map class. Each such element is inspected for the _leaflet_id attribute described above. If the _leaflet_id attribute is present, the processAddedNodes function must have added the map. This means the _leaflet_id value will be in the global maps dictionary and can be used to obtain the corresponding Leaflet map instance, allowing its remove() method to be invoked. The corresponding maps and mapLayers entries are then nulled out.

function processRemovedNodes(removedNodes) {
    removedNodes.forEach(function(n) {
        if (n.getElementsByClassName == null) return;

        var elements = n.getElementsByClassName("leaflet-map");
        Array.prototype.forEach.call(elements, function(element) {
            if (element._leaflet_id != null) {
                console.log("removing map with leaflet id", element._leaflet_id);
                maps[element._leaflet_id].remove();
                maps[element._leaflet_id] = null;
                mapLayers[element._leaflet_id] = null;
            }
        });
    });
}

Final thoughts

The method described in this article seems to work fairly well, and it is what I am currently using in my project. I can't say it is entirely satisfactory, because there is quite a bit of incidental complexity, all of which is on the unsafe Javascript side of the interface.

I will undoubtedly be revisiting this code. There other features that are needed including selecting regions and synchronizing the view between multiple maps.