utilities – Helper functions

The utilities package is the standard home for shared functions which many modules may use. The spirit of utilities is also to isolate sections of critical code so that unit tests can be used to ensure a minimum of bugginess.

Automaton Helpers

Chat Formatting

Colorizers.

bravo.utilities.chat.sanitize_chat(s)

Verify that the given chat string is safe to send to Notchian recepients.

bravo.utilities.chat.username_alternatives(n)

Permute a username through several common alternative-finding algorithms.

Coordinate Handling

Utilities for coordinate handling and munging.

bravo.utilities.coords.adjust_coords_for_face(coords, face)

Adjust a set of coords according to a face.

The face is a standard string descriptor, such as “+x”.

The “noop” face is supported.

bravo.utilities.coords.split_coords(x, z)

Split a pair of coordinates into chunk and subchunk coordinates.

Parameters:

• x (int) – the X coordinate
• z (int) – the Z coordinate

Returns:

a tuple of the X chunk, X subchunk, Z chunk, and Z subchunk

bravo.utilities.coords.taxicab2(x1, y1, x2, y2)

Return the taxicab distance between two blocks.

bravo.utilities.coords.taxicab3(x1, y1, z1, x2, y2, z2)

Return the taxicab distance between two blocks, in three dimensions.

Data Packing

More affectionately known as “bit-twiddling.”

Decorators

General decorators for a variety of purposes.

Geometry

bravo.utilities.geometry.gen_line_covered(point1, point2)

This is Bresenham’s algorithm with a little twist: all the blocks that intersect with the line are yielded.

bravo.utilities.geometry.gen_line_simple(point1, point2)

Generalization of Bresenham’s line algorithm in 3d.

It yields blocks coordinates along a line that is at all times only one block in width.

It is a simplified version that does nothing fancy with integers or such: all computation is done on float (maybe it should be changed?)

Scheduling

Spatial Hashes

class bravo.utilities.spatial.Block2DSpatialDict

Bases: bravo.utilities.spatial.SpatialDict

Class for tracking blocks in the XZ-plane.

key_for_bucket(key)

Partition keys into chunk-sized buckets.

keys_near(key, radius)

Get all bucket keys “near” this key.

This method may return a generator.

class bravo.utilities.spatial.Block3DSpatialDict

Bases: bravo.utilities.spatial.SpatialDict

Class for tracking blocks in the XZ-plane.

key_for_bucket(key)

Partition keys into chunk-sized buckets.

keys_near(key, radius)

Get all bucket keys “near” this key.

This method may return a generator.

class bravo.utilities.spatial.SpatialDict

Bases: object, UserDict.DictMixin

A spatial dictionary, for accelerating spatial lookups.

This particular class is a template for specific spatial dictionaries; in order to make it work, subclass it and add key_for_bucket().

iteritemsnear(key, radius)

A version of iteritems() that filters based on the distance from a given key.

The key does not need to actually be in the dictionary.

iterkeys()

Yield all the keys.

iterkeysnear(key, radius)

Yield all of the keys within a certain radius of this key.

itervaluesnear(key, radius)

Yield all of the values within a certain radius of this key.

keys()

Get a list of all keys in the dictionary.

Trigonometry

bravo.utilities.maths.morton2(x, y)

Create a Morton number by interleaving the bits of two numbers.

This can be used to map 2D coordinates into the integers.

Inputs will be masked off to 16 bits, unsigned.

bravo.utilities.maths.rotated_cosine(x, y, theta, lambd)

Evaluate a rotated 3D sinusoidal wave at a given point, angle, and wavelength.

The function used is:

This function has a handful of useful properties; it has a local minimum at f(0, 0) and oscillates infinitely betwen 0 and 1.

Parameters:

• x (float) – X coordinate
• y (float) – Y coordinate
• theta (float) – angle of rotation
• lambda (float) – wavelength

Returns:

float of f(x, y)