menpo/menpo — pull request #470 by jabooth (2014-10-09 20:59:05+00:00)
Title: expensive properties should really be methods

Computed properties are great for keeping code clean. Small computations or remapping's of values (e.g. `pixels.shape[0] == width`) are excellent candidates for properties, because the computation is fast. This is important, as in general the user **doesn't know that any computation is going on** - when coding, using a property *feels* the same as accessing an attribute (cheap and fast) regardless of how expensive the call actually is. For this reason, expensive properties can be confusing.

As an example, say we have the following:

```python
n_x = mesh.vertex_normals[0]
n_y = mesh.vertex_normals[1]
n_z = mesh.vertex_normals[2]
```
This doesn't look like a particularly troubling block of code, but in reality `vertex_normal` is an expensive computed property, so it would be appropriate (and 3x faster) to do the following:
```python
vn = mesh.vertex_normals
n_x = vn[0]
n_y = vn[1]
n_z = vn[2]
```
The issue is that the user has no way of knowing that this is an expensive operation that should be cached in such a manner. There is a simple change that makes the behavior much more apparent - just make `vertex_normals` a method!
```python
vn = mesh.vertex_normals()
n_x = vn[0]
n_y = vn[1]
n_z = vn[2]
```
Now the user would think twice about calling the method needlessly many times.

This PR goes through the shape module and changes a number of properties to methods. The rule I've tried to follow is -

> *would I wince if I saw the property being called multiple times in a row?*

The ones I've done here are:

- `PointCloud.h_points`
- `PointCloud.centre`
- `PointCloud.centre_of_bounds`
- `Mesh.vertex_normals`
- `Mesh.face_normals`