Each instance of this class is a container for all the photos that depict members of a specific taxon. Instances are arranged in the form of a tree. The root node is a container for the entire catalog, and represents the root taxon of birds, Class Aves.
Here is the interface. The constructor takes one argument: the taxon related to this node.
# - - - - - c l a s s T a x o n P h o t o S e t class TaxonPhotoSet: '''Represents all photos contained in a specific taxon. Exports: TaxonPhotoSet(taxon): [ taxon is a txny.Taxon instance -> return a new, empty TaxonPhotoSet for that taxon ] .taxon: [ as passed to constructor; read-only ] .nContained: [ number of photos in self's subtree ] .nReferred: [ number of photos referred to self's taxon ]
.addArchImage() method is used to load
catalog entries into the tree. For each photo, this
method is called once for each kind of bird in the photo.
Note the precondition that the specified
must be referred to a taxon that is either
or a descendant of
self. It simplifies the logic
of adding a new photo to know that the photo goes somewhere in
the correct subtree. It is no burden on the caller who adds the
photo to the root of the tree, since all birds are in class
Aves. See Section 11.2, “
TaxonPhotoSet.addArchImage(): Add one
.addArchImage(birdId, archImage): [ birdId is referred to a taxon contained in self.taxon -> (birdId is a composite bird form code as an abbr.BirdId object) and (archImage is an image catalog entry as a archindex.ArchImage instance) -> self := self with archImage added under birdId ]
.walk() method walks the tree, starting
at the given node, and then recursively visiting its
descendants. This method is called to generate the various
taxonomic headings on the index page. See Section 11.5, “
TaxonPhotoSet.walk(): Walk the tree”.
.walk(): [ generate self, followed by the descendants of self, in preorder traversal ]
Because the presentation of a taxon with only one form is
different than the presentation of a multi-form taxon, the
.nForms() method allows the caller to
determine the number of forms. See Section 11.6, “
TaxonPhotoSet.nForms(): Number of
.nForms(): [ returns the number of forms in self ]
.genForms() method generates the
FormPhotoSet objects in order.
See Section 11.7, “
.genForms(): [ generate the FormPhotoSet objects in self, in ascending order by inverted English name ]
Here are the internals of the instance. Each node
maintains two counters. The
attribute counts all the photos ever added to this node's
.nReferred attribute is a
count of only those photos referred to this node's taxon.
TaxonPhotoSet instance is a container
for two kinds of objects: child taxa, and
FormPhotoSet instances for any photos that may be
referred to this taxon.
One of the author's favorite standard Python tricks serves nicely to structure both these container relationships: we keep the contained values in a dictionary, and access them using a key that happens to sort in the desired access order.
The standard Python trick is: use the dictionary's
.keys() method to extract a list of keys; sort
that list; and then go through the dictionary in order
using that list.
.childMap contains the child
TaxonPhotoSet elements as values. In order
to access the children in taxonomic order, we use the
txKey attribute of the taxon as the key, which is
a string of digits that orders taxa in phylogenetic order.
State/Internals: ._childMap: [ a dictionary whose values are the child TaxonPhotoSet nodes of self, and each corresponding key is the .txKey attribute of self's taxon ]
The desired order of form names within a taxon is alphabetical order by the inverted English name.
._formMap: [ a dictionary whose values are the FormPhotoSet objects holding photos referred to self.taxon, and each corresponding key is the inverted English name for that form ] '''