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.polar_round_vector(vector)

Rounds a vector towards zero

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.

bravo.utilities.decos.timed(f)

Print out timing statistics on a given callable.

Intended largely for debugging; keep this in the tree for profiling even if it’s not currently wired up.

Geometry

Simple pixel graphics helpers.

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

Retrieve the first integer set of coordinates on the line from the first point to the second point.

The set of coordinates corresponding to the first point will not be retrieved.

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)

An adaptation of Bresenham’s line algorithm in three dimensions.

This function returns an iterable of integer coordinates along the line from the first point to the second point. No points are omitted.

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.clamp(x, low, high)

Clamp or saturate a number to be no lower than a minimum and no higher than a maximum.

Implemented as its own function simply because it’s so easy to mess up when open-coded.

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)