lulu 0.0.2

data/ext/lulu/qt.c

@@ -0,0 +1,299 @@
+/*
+ * qt.c
+ *
+ *  Created on: Mar 17, 2014
+ *      Author: generessler
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <assert.h>
+#include "qt.h"
+#include "utility.h"
+#include "test.h"
+
+// Declare the given quadrant of a given bounding box.
+#define QUADRANT_DECL(Q, QX, QY, QW, QH, X, Y, W, H) \
+  double QW = W * 0.5; \
+  double QH = H * 0.5; \
+  double QX = (Q & 1) ? X + QW : X; \
+  double QY = (Q & 2) ? Y + QH : Y
+
+// Initialize a node to an empty leaf.
+static void init_leaf(NODE *node) {
+	node->children = NULL;
+	node->markers = NULL;
+	node->marker_count = node->markers_size = 0;
+}
+
+// Clear contents of a leaf, returning it to the init_leaf state.
+static void clear_leaf(NODE *node) {
+	Free(node->markers);
+	init_leaf(node);
+}
+
+// Make a leaf into an internal node with four empty leaves.
+static void subdivide(NODE *node) {
+	if (leaf_p(node)) {
+		NewArray(node->children, 4);
+		for (int i = 0; i < 4; i++)
+			init_leaf(node->children + i);
+	}
+}
+
+static void clear_node(NODE *node);
+
+// Recursively clear an internal node by removing all
+// subtrees, returning this node to the init_leaf state.
+static void clear_internal(NODE *node) {
+	for (int i = 0; i < 4; i++)
+		clear_node(node->children + i);
+	Free(node->children);
+	clear_leaf(node);
+}
+
+// Clear any node, returning it to the init_leaf state.
+// Recursively removes all subtrees.
+static void clear_node(NODE *node) {
+	if (internal_p(node))
+		clear_internal(node);
+	else
+		clear_leaf(node);
+}
+
+// Add a marker to the given node's marker list.
+static void add_marker(NODE *node, MARKER *marker) {
+	if (node->marker_count == node->markers_size) {
+		node->markers_size = 2 + 2 * node->markers_size;
+		RenewArray(node->markers, node->markers_size);
+	}
+	node->markers[node->marker_count++] = marker;
+}
+
+// Find a marker in the given node's marker list.
+static int find_marker(NODE *node, MARKER *marker) {
+	for (int i = 0; i < node->marker_count; i++)
+		if (node->markers[i] == marker)
+			return i;
+	return -1;
+}
+
+// Delete a marker from the given node's marker list.
+static int delete_marker(NODE *node, MARKER *marker) {
+	int i = find_marker(node, marker);
+	if (i != -1 && --node->marker_count != 0)
+		node->markers[i] = node->markers[node->marker_count];
+	return i;
+}
+
+// Return non-zero iff the given bounding box lies inside the marker including its boundary.
+static int bounds_inside_marker(double x, double y, double w, double h, MARKER *marker) {
+	double mx = mr_x(marker);
+	double my = mr_y(marker);
+	double mr = mr_r(marker);
+	return mx - mr <= x && x + w <= mx + mr && my - mr <= y && y + h <= my + mr ;
+}
+
+// Return an integer code with bits showing which quadrants of the given
+// bounding box are overlapped by the given marker.
+static int touch_code(double x, double y, double w, double h, MARKER *marker) {
+	double xm = x + 0.5 * w;
+	double ym = y + 0.5 * h;
+	int code = bit(SW) | bit(SE) | bit(NW) | bit(NE);
+	if (mr_e(marker) < xm) code &= ~(bit(NE) | bit(SE));
+	if (mr_w(marker) > xm) code &= ~(bit(NW) | bit(SW));
+	if (mr_n(marker) < ym) code &= ~(bit(NW) | bit(NE));
+	if (mr_s(marker) > ym) code &= ~(bit(SW) | bit(SE));
+	return code;
+}
+
+// Insert the given marker into the quadtree with given root and corresponding bounding box,
+// subdividing no more than the given number of levels.
+static void insert(NODE *node, int levels, double x, double y, double w, double h, MARKER *marker) {
+	if (bounds_inside_marker(x, y, w, h, marker) || levels == 0)
+		add_marker(node, marker);
+	else {
+		if (leaf_p(node))
+			subdivide(node);
+		int code = touch_code(x, y, w, h, marker);
+		for (int q = 0; q < 4; q++)
+			if (code & bit(q)) {
+				QUADRANT_DECL(q, qx, qy, qw, qh, x, y, w, h);
+				insert(node->children + q, levels - 1, qx, qy, qw, qh, marker);
+			}
+	}
+}
+
+// A helper function that returns true iff the given array of 4 child quadtrees are all empty leaves.
+static int empty_leaves_p(NODE *children) {
+	for (int i = 0; i < 4; i++)
+		if (internal_p(children + i) || children[i].marker_count > 0)
+			return 0;
+	return 1;
+}
+
+// Delete the given marker from the quadtree with given root and corresponding bounding box,
+// trimming any remaining empty leaves.
+static void delete(NODE *node, int levels, double x, double y, double w, double h, MARKER *marker) {
+	if (bounds_inside_marker(x, y, w, h, marker) || levels == 0)
+		delete_marker(node, marker);
+	else if (internal_p(node)){
+		int code = touch_code(x, y, w, h, marker);
+		for (int q = 0; q < 4; q++)
+			if (code & bit(q)) {
+				QUADRANT_DECL(q, qx, qy, qw, qh, x, y, w, h);
+				delete(node->children + q, levels - 1, qx, qy, qw, qh, marker);
+			}
+		if (empty_leaves_p(node->children))
+			Free(node->children);
+	}
+}
+
+// Local struct to hold information about the nearest marker seen so far in a search.
+struct nearest_info {
+    MARKER_INFO *info;
+    MARKER *target, *nearest;
+	double distance;
+};
+
+// Use the marker list of the given node to update nearest information with
+// respect to the given marker.
+static void update_nearest(NODE *node, struct nearest_info *nearest_info) {
+	for (int i = 0; i < node->marker_count; i++) {
+		// This < assumes the markers are in an array. It sustains the invariant.
+		if (node->markers[i] < nearest_info->target) {
+			double d = mr_distance(nearest_info->info, nearest_info->target, node->markers[i]);
+			if (d < nearest_info->distance) {
+				nearest_info->distance = d;
+				nearest_info->nearest = node->markers[i];
+			}
+		}
+	}
+}
+
+// Search out the nearest marker that overlaps the given one.  This just visits every
+// quad that overlaps the given marker and remembers the closest marker it sees. The
+// circle distance function renders quite impossible the ruling out of quads as in
+// nearest point neighbor search.
+static void search_for_nearest(NODE *node, double x, double y, double w, double h, struct nearest_info *nearest_info) {
+	update_nearest(node, nearest_info);
+	if (internal_p(node)) {
+		// Search the children that include some part of the marker.
+		int code = touch_code(x, y, w, h, nearest_info->target);
+		for (int q = 0; q < 4; q++)
+			if (code & bit(q)) {
+				QUADRANT_DECL(q, qx, qy, qw, qh, x, y, w, h);
+				search_for_nearest(node->children + q, qx, qy, qw, qh, nearest_info);
+			}
+	}
+}
+
+static MARKER *nearest(MARKER_INFO *info, NODE *node, double x, double y, double w, double h, MARKER *marker) {
+	struct nearest_info nearest_info[1] = {{ info, marker, NULL, 0 }};
+	search_for_nearest(node, x, y, w, h, nearest_info);
+	return nearest_info->nearest;
+}
+
+void qt_init(QUADTREE *qt) {
+	init_leaf(qt->root);
+	qt->x = qt->y = qt->w = qt->h = 0;
+}
+
+void qt_setup(QUADTREE *qt, int max_depth, double x, double y, double w, double h, MARKER_INFO *info) {
+	qt->x = x;
+	qt->y = y;
+	qt->w = w;
+	qt->h = h;
+	qt->max_depth = max_depth;
+	qt->info = info;
+}
+
+void qt_clear(QUADTREE *qt) {
+	clear_node(qt->root);
+	qt_init(qt);
+}
+
+void qt_insert(QUADTREE *qt, MARKER *marker) {
+	double x = mr_x(marker);
+	double y = mr_y(marker);
+	double r = mr_r(marker);
+	if (x + r >= qt->x && x - r <= qt->x + qt->w && y + r >= qt->y && y - r <= qt->y + qt->h)
+		insert(qt->root, qt->max_depth, qt->x, qt->y, qt->w, qt->h, marker);
+}
+
+void qt_delete(QUADTREE *qt, MARKER *marker) {
+	delete(qt->root, qt->max_depth, qt->x, qt->y, qt->w, qt->h, marker);
+}
+
+MARKER *qt_nearest(QUADTREE *qt, MARKER *marker) {
+	return nearest(qt->info, qt->root, qt->x, qt->y, qt->w, qt->h, marker);
+}
+
+int qt_nearest_wrt(MARKER *markers, QUADTREE *qt, int a) {
+	MARKER *nearest = qt_nearest(qt, markers + a);
+	return nearest ? (int)(nearest - markers) : -1;
+}
+
+#ifndef EXCLUDE_UNIT_TEST
+
+static void draw(FILE *f, NODE *node, double x, double y, double w, double h) {
+	emit_rectangle(f, x, y, w, h);
+	emit_marker_ptr_array(f, node->markers, node->marker_count);
+	if (internal_p(node)) {
+		for (int q = 0; q < 4; q++) {
+			QUADRANT_DECL(q, qx, qy, qw, qh, x, y, w, h);
+			draw(f, node->children + q, qx, qy, qw, qh);
+		}
+	}
+}
+
+static void draw_nearest(FILE *f, MARKER *markers, MARKER **nearest_markers, int n_markers) {
+	for (int i = 0; i < n_markers; i++) {
+		if (nearest_markers[i])
+			emit_segment(f, markers + i, nearest_markers[i]);
+	}
+}
+
+int qt_draw(QUADTREE *qt, MARKER *markers, MARKER **nearest_markers, int n_markers, const char *name) {
+	char buf[1024];
+	sprintf(buf, "test/%s.js", name);
+	FILE *f = fopen(buf, "w");
+	if (!f)
+		return -1;
+	fprintf(f, "var %s = [\n", name);
+	draw(f, qt->root, qt->x, qt->y, qt->w, qt->h);
+	draw_nearest(f, markers, nearest_markers, n_markers);
+	fprintf(f, "];\n");
+	fclose(f);
+	return EXIT_SUCCESS;
+}
+
+int qt_test(int size) {
+	QUADTREE_DECL(qt);
+	MARKER_INFO_DECL(info);
+	MARKER *markers, **nearest_markers;
+	NewArray(markers, size);
+	NewArray(nearest_markers, size);
+	set_random_markers(info, markers, size);
+	qt_setup(qt, 5, 0, 0, 1024, 724, info);
+	fprintf(stderr, "inserting %d:\n", size);
+	for (int i = 0; i < size; i++) {
+		qt_insert(qt, markers + i);
+	}
+	fprintf(stderr, "inserted %d\n", size);
+	for (int i = 0; i < size; i++) {
+		nearest_markers[i] = qt_nearest(qt, markers + i);
+	}
+	fprintf(stderr, "looked up %d\n", size);
+	qt_draw(qt, markers, nearest_markers, size, "qt");
+	fprintf(stderr, "drew %d\n", size);
+	for (int i = 0; i < size; i++) {
+		qt_delete(qt, markers + i);
+	}
+	fprintf(stderr, "after delete all, root is %s\n",
+			leaf_p(qt->root) ? "leaf (ok)" : "internal (not ok)");
+
+	return EXIT_SUCCESS;
+}
+
+#endif

data/ext/lulu/qt.h

@@ -0,0 +1,57 @@
+/*
+ * qt.h
+ *
+ *  Created on: Mar 17, 2014
+ *      Author: generessler
+ */
+
+#ifndef QT_H_
+#define QT_H_
+
+#include "marker.h"
+
+typedef struct node_s {
+	struct node_s *children;
+	MARKER **markers;
+	int marker_count, markers_size;
+} NODE;
+
+#define leaf_p(Node) ((Node)->children == NULL)
+#define internal_p(Node) ((Node)->children != NULL)
+
+// These are chosen so the 1's bit encodes the
+// quadrant x location and the 2's bit encodes y
+//
+//  ---------------
+// |       |       |
+// |  1 0  |  1 1  |
+// |       |       |
+//  ---------------
+// |       |       |
+// |  0 0  |  0 1  |
+// |       |       |
+//  ---------------
+#define SW 0
+#define SE 1
+#define NW 2
+#define NE 3
+
+typedef struct quadtree_s {
+	double x, y, w, h;
+	int max_depth;
+	MARKER_INFO *info;
+	NODE root[1];
+} QUADTREE;
+
+#define QUADTREE_DECL(Name) QUADTREE Name[1]; qt_init(Name)
+
+void qt_init(QUADTREE *qt);
+void qt_setup(QUADTREE *qt, int max_depth, double x, double y, double w, double h, MARKER_INFO *info);
+void qt_insert(QUADTREE *qt, MARKER *marker);
+void qt_delete(QUADTREE *qt, MARKER *marker);
+MARKER *qt_nearest(QUADTREE *qt, MARKER *marker);
+int qt_nearest_wrt(MARKER *markers, QUADTREE *qt, int a);
+void qt_clear(QUADTREE *qt);
+int qt_test(int size);
+
+#endif /* QT_H_ */

data/ext/lulu/test.c

@@ -0,0 +1,82 @@
+/*
+ * test.c
+ *
+ *  Created on: Mar 21, 2014
+ *      Author: generessler
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <stdarg.h>
+#include <time.h>
+#include "test.h"
+#include "utility.h"
+
+void emit_rectangle(FILE *f, double x, double y, double w, double h) {
+	fprintf(f, "  { kind: 'r', color: 'lightGray', p0: { x: %.2f, y: %.2f }, p1: { x: %.2f, y: %.2f } },\n", x, y, x + w, y + h);
+}
+
+void emit_segment(FILE *f, MARKER *a, MARKER *b) {
+	fprintf(f, "  { kind: 's', color: 'red', p0: { x: %.2f, y: %.2f }, p1: { x: %.2f, y: %.2f } },\n",
+			mr_x(a), mr_y(a), mr_x(b), mr_y(b));
+}
+
+int emit_marker_ptr_array(FILE *f, MARKER **markers, int n_markers) {
+	int n_emitted = 0;
+	for (int i = 0; i < n_markers; ++i) {
+		MARKER *m = markers[i];
+		if (!m->deleted_p) {
+			fprintf(f, "  { kind: 'm', x: %.2f, y: %.2f, r: %.2f }, // %d\n", mr_x(m), mr_y(m), mr_r(m), i);
+			n_emitted++;
+		}
+	}
+	return n_emitted;
+}
+
+int emit_marker_array(FILE *f, MARKER *markers, int n_markers) {
+	int n_emitted = 0;
+	for (int i = 0; i < n_markers; ++i) {
+		MARKER *m = markers + i;
+		if (!m->deleted_p) {
+			fprintf(f, "  { x: %.2f, y: %.2f, r: %.2f }, // %d\n", mr_x(m), mr_y(m), mr_r(m), i);
+			n_emitted++;
+		}
+	}
+	return n_emitted;
+}
+
+int emit_markers(const char *name, MARKER *markers, int n_markers) {
+	char buf[1024];
+	sprintf(buf, "test/%s.js", name);
+	FILE *f = fopen(buf, "w");
+	if (!f)
+		return -1;
+	fprintf(f, "var %s = [\n", name);
+	int n_emitted = emit_marker_array(f, markers, n_markers);
+	fprintf(f, "];");
+	fclose(f);
+	return n_emitted;
+}
+
+void set_random_markers(MARKER_INFO *info, MARKER *markers, int n_markers) {
+	unsigned t = (unsigned)time(0);
+	fprintf(stderr, "seed=%u\n", t);
+	srand(t);
+	int size = 8;
+	double x_size = 1024;
+	double y_size = 760;
+	for (int i = 0; i < n_markers; i++)
+		mr_set(info, markers + i, x_size * rand_double(), y_size * rand_double(), 1 + random() % (size - 1));
+}
+
+int trace_p = 1;
+
+void trace(const char *fmt, ...)
+{
+	if (trace_p) {
+		va_list ap;
+		va_start(ap, fmt);
+		vfprintf(stderr, fmt, ap);
+		va_end(ap);
+	}
+}

data/ext/lulu/test.h

@@ -0,0 +1,20 @@
+/*
+ * test.h
+ *
+ *  Created on: Mar 21, 2014
+ *      Author: generessler
+ */
+
+#ifndef TEST_H_
+#define TEST_H_
+
+#include "marker.h"
+
+int emit_markers(const char *name, MARKER *markers, int n_markers);
+void emit_rectangle(FILE *f, double x, double y, double w, double h);
+void emit_segment(FILE *f, MARKER *a, MARKER *b);
+int emit_marker_array(FILE *f, MARKER *markers, int n_markers);
+int emit_marker_ptr_array(FILE *f, MARKER **markers, int n_markers);
+void set_random_markers(MARKER_INFO *info, MARKER *markers, int n_markers);
+
+#endif /* TEST_H_ */

data/ext/lulu/utility.c

@@ -0,0 +1,49 @@
+/*
+ * utility.c
+ *
+ *  Created on: Feb 23, 2014
+ *      Author: generessler
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "utility.h"
+
+void *safe_malloc(size_t size, const char *file, int line) {
+	void *p = malloc(size);
+	if (!p) {
+		fprintf(stderr, "%s:%d: out of memory\n", file, line);
+		exit(1);
+	}
+	return p;
+}
+
+void *safe_realloc(void *p, size_t size, const char *file, int line) {
+	p = realloc(p, size);
+	if (!p) {
+		fprintf(stderr, "%s:%d: out of memory\n", file, line);
+		exit(1);
+	}
+	return p;
+}
+
+/**
+ * Return the 0-based position of highest bit or -1 of zero.
+ */
+int high_bit_position(unsigned n) {
+	int p = -1;
+	while (n) {
+		p++;
+		n >>= 1;
+	}
+	return p;
+}
+
+double rand_double(void)
+{
+	unsigned i = rand();
+	i = (i << 8) ^ (unsigned)rand();
+	i = (i << 8) ^ (unsigned)rand();
+	i = (i << 8) ^ (unsigned)rand();
+	return i / (256.0 * 256.0 * 256.0 * 256.0);
+}

data/ext/lulu/utility.h

@@ -0,0 +1,74 @@
+/*
+ * utility.h
+ *
+ *  Created on: Feb 23, 2014
+ *      Author: generessler
+ */
+
+#ifndef UTILITY_H_
+#define UTILITY_H_
+
+#define STATIC_ARRAY_SIZE(A) ((int)(sizeof A / sizeof A[0]))
+
+#ifdef NOT_RUBY_EXTENSION
+
+// Our allocators.
+#define New(Ptr) do { \
+	(Ptr) = safe_malloc(sizeof *(Ptr), __FILE__, __LINE__); \
+} while (0)
+
+#define NewArray(Ptr, Size) do { \
+	(Ptr) = safe_malloc((Size) * sizeof *(Ptr), __FILE__, __LINE__); \
+} while (0)
+
+#define RenewArray(Ptr, Size) do { \
+	(Ptr) = safe_realloc((Ptr), (Size) * sizeof *(Ptr), __FILE__, __LINE__); \
+} while (0)
+
+#define Free(Ptr) do { \
+	free(Ptr); \
+	Ptr = NULL; \
+} while (0)
+
+#else
+
+#include "ruby.h"
+
+// Ruby allocators.  We can't use the macros without rewriting to include type parameters.
+#define New(Ptr) do { \
+	(Ptr) = (void*)xmalloc(sizeof *(Ptr)); \
+} while (0)
+
+#define NewArray(Ptr, Size) do { \
+	(Ptr) = (void*)xmalloc2((Size), sizeof *(Ptr)); \
+} while (0)
+
+#define RenewArray(Ptr, Size) do { \
+	(Ptr) = (void*)xrealloc2((char*)(Ptr), (Size), sizeof *(Ptr)); \
+} while (0)
+
+#define Free(Ptr) do { \
+	Ptr = NULL; \
+} while (0)
+
+#endif
+
+#define NewDecl(Type, Ptr) Type *Ptr; New(Ptr)
+#define NewArrayDecl(Type, Ptr, Size) Type *Ptr; NewArray(Ptr, Size)
+#define CopyArray(Dst, Src, N)   memcpy((Dst), (Src), (N) * sizeof *(Src))
+
+#define bit(N) (1u << (N))
+
+#ifndef NTRACE
+#define TRACE(Args)  trace Args
+void trace(const char *fmt, ...);
+#else
+#define TRACE(Args)
+#endif
+
+void *safe_malloc(size_t size, const char *file, int line);
+void *safe_realloc(void *p, size_t size, const char *file, int line);
+int high_bit_position(unsigned n);
+double rand_double(void);
+
+#endif /* UTILITY_H_ */

data/lib/lulu/version.rb

@@ -0,0 +1,3 @@
+module Lulu
+  VERSION = "0.0.2"
+end

data/lib/lulu.rb

@@ -0,0 +1,14 @@
+require "lulu/version"
+require "lulu/lulu"
+
+module Lulu
+  class MarkerList
+
+    def markers
+      list = []
+      length.times {|i| list << marker(i) unless deleted(i) }
+      list
+    end
+
+  end
+end

data/lulu.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lulu/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "lulu"
+  spec.version       = Lulu::VERSION
+  spec.authors       = ["Gene Ressler"]
+  spec.email         = ["gene.ressler@gmail.com"]
+  spec.summary       = %q{Merge map markers by agglomerative clustering.}
+  spec.description   =
+%q{Lulu merges the closest overlapping pair of map markers into a one whose
+area is the sum of the original two, located at their centroid. It repeats
+this until no overlaps remain. Some interesting data structures make this
+quite fast for all but pathologically bad data. Markers can be circles or
+squares. The user may provide a scale factor allowing the marker radius to
+have a different scale than distance between markers.}
+  spec.homepage      = "https://github.com/gene-ressler/lulu/wiki"
+  spec.licenses      = "GPL-3.0"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.extensions  = ['ext/lulu/extconf.rb']
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 10.1"
+  spec.add_development_dependency "rake-compiler"
+  spec.add_development_dependency "rspec", "~> 2.14"
+end

data/spec/lib/lulu_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+# Test the Lulu API.
+describe Lulu do
+
+  it 'should report version' do
+    Lulu::VERSION.should_not be_nil
+  end
+
+  it 'should report extension code version' do
+    Lulu::EXT_VERSION.should_not be_nil
+  end
+
+end

data/spec/lib/marker_list_spec.rb

@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+# Test the Lulu API.
+describe Lulu::MarkerList do
+
+  TEST_SIZE = 10000
+
+  let(:list) do
+    list = Lulu::MarkerList.new
+    srand(42)
+    TEST_SIZE.times{ |n| list.add(Random.rand(1000), Random.rand(1000), Random.rand(100)) }
+    list
+  end
+
+  it 'should have length matching number of markers added' do
+    list.length.should == TEST_SIZE
+  end
+
+  it 'should merge to correct number of markers' do
+    list.merge.should == 17362
+  end
+
+  it 'should compress to correct number of markers after merge' do
+    list.merge
+    list.compress.should == 2638
+  end
+
+  it 'should have idempotent merge' do
+    list.merge
+    list.compress == list.merge
+  end
+
+  it 'should have correct number of non-merged nodes in parts' do
+    n = 0
+    list.merge.times{|i| n += 1 if [:root, :single].include? list.parts(i)[0] }
+    n.should == list.compress
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'lulu'