API Documentation¶

Metadata keys¶

Various points in the model and search classes use metadata. These are extensible fields, used to enrich the information provided by an Event or FileRecord, and consist of a key and value. The value may be numeric, time or text, and the keys can, in theory, be anything. Obviously to sensibly search for and interpret these metadata values you’ll need to have an idea of the possible keys and their meanings. These are maintained on our wiki at https://github.com/camsci/meteor-pi/wiki/List-of-metadata-fields

Semantic types¶

In a similar fashion, we use a namespaced string to specify the semantic type of both Event and FileRecord objects. The semantic type is used to indicate the meaning of the object - an Event may have a semantic type indicating that it’s an observation of a meteor as opposed to a satellite, a FileRecord may have one to denote that it’s a timelapse image rather than some other image. Note in particular that FileRecords also have a MIME type, the MIME type denotes the format of the file whereas the semantic type indicates its contents.

As there’s a potentially infinite number of these types we maintain a list of the semantic types used by the MeteorPi project at https://github.com/camsci/meteor-pi/wiki/List-of-semantic-types. Other projects may extend this set of types, but this should always contain an up-to-date list of the values we use within the project. Use this to find out what to put in your queries, and to interpret the values in the objects those queries retrieve.

FileRecord¶

class meteorpi_model.FileRecord(camera_id, mime_type, semantic_type, status_id, file_name=None, md5=None)[source]¶

Represents a single data file, either within an Event instance or stand-alone. You will typically not construct FileRecord instances yourself, rather using the search methods in the client, or (for internal use) the register methods in the database API.

Variables:

camera_id (string) – String ID of the camera which produced this file. status_id (uuid.UUID) – UUID of the CameraStatus describing the state, location, lens type and similar properties of the camera at the time the file was created. file_id (uuid.UUID) – UUID of the file itself. file_time (datetime.datetime) – Datetime the file was created on the camera. file_size (int) – File size in bytes. A value of 0 means that the underlying file is not yet available, so it cannot be downloaded. This may happen if you are retrieving results from a central server which has received the information about a file from another system (i.e. a camera) but has not yet received the actual file. file_name (string) – Optional, and can be None, this contains a suggested name for the file. This is used in the web interface to show the file name to download, but is not guaranteed to be unique (if you need a unique ID you should use the file_id) mime_type (string) – MIME type of the file, typically used to determine which application opens it. Values are strings like ‘text/plain’ and ‘image/png’ semantic_type (NSString) – Semantic type of the file. This defines the meaning of the contents (mime_type defining the format of the contents). This is a meteorpi_model.NSString, and can take any arbitrary value. You should consult the documentation for the particular project you’re working with for more information on what might appear here. meta (list[Meta]) – List of zero or more meteorpi_model.Meta objects. Meta objects are used to provide arbitrary extra, searchable, information about the file and its contents. md5 (string) – The hex representation of the MD5 sum for the data held by this FileRecord, as computed by model.get_md5_hash()

__init__(camera_id, mime_type, semantic_type, status_id, file_name=None, md5=None)[source]¶

Event¶

class meteorpi_model.Event(camera_id, event_time, event_id, event_type, status_id, file_records=None, meta=None)[source]¶

Represents a single interpretation. You can think of the FileRecord as being an observation, and the Event as being an interpretation of one or more observations (i.e. the files may contain images of a flashing light in the sky, and the event contains inferred information that it’s a flying saucer). You typically won’t create Event instances, instead you will use the client API to search for them, or (for internal use) the database API to register them.

Variables:

camera_id (string) – the string ID of the camera which produced this event. status_id (uuid.UUID) – the UUID of the CameraStatus describing the state, location, lens type and similar properties of the camera at the time the event was created. event_id (uuid.UUID) – the UUID of the event itself. event_time (datetime.datetime) – the datetime the event was created on the camera. event_type (NSString) – the semantic type of the event. The semantic type is used to describe the kind of event, so we might have a semantic type for an event meaning ‘we think this is a meteor’, for example. This is an NSString, and can take any arbitrary value. You should consult the documentation for the particular project you’re working with for more information on what might appear here. file_records (list[FileRecord]) – a list of zero or more meteorpi_model.FileRecord objects. You can think of these as the supporting evidence for the other information in the event. meta (list[Meta]) – a list of zero or more meteorpi_model.Meta objects. Meta objects are used to provide arbitrary extra, searchable, information about the event.

__init__(camera_id, event_time, event_id, event_type, status_id, file_records=None, meta=None)[source]¶

Constructor function. Note that typically you’d use the methods on the database to create a new Event, or on the client API to retrieve an existing one. This constructor is only for internal use within the database layer.

Parameters:

camera_id (string) – Camera ID which is responsible for this event event_time (datetime.datetime) – Date for the event event_id (uuid.UUID) – UUID for this event event_type (NSString) – meteorpi_model.NSString defining the event type, we use this because the concept of a meteorpi_model.Event has evolved beyond being restricted to meteor sightings. file_records (list[FileRecord]) – A list of meteorpi_model.FileRecord, or None to specify no files, which support the event. meta (list[Meta]) – A list of meteorpi_model.Meta, or None to specify an empty list, which provide additional information about the event.

Meta¶

class meteorpi_model.Meta(key, value)[source]¶

A single piece of metadata pertaining to a FileRecord or an Event.

Variables:	key (NSString) – Name of this metadata property, specified as an NSString value (object) – Value of this property, this can be a Number, string or datetime.datetime

__init__(key, value)[source]¶

type()[source]¶

Returns ‘number’, ‘string’, ‘date’ or ‘unknown’ based on the type of the value

FileRecordSearch¶

class meteorpi_model.FileRecordSearch(camera_ids=None, lat_min=None, lat_max=None, long_min=None, long_max=None, after=None, before=None, mime_type=None, semantic_type=None, exclude_events=False, after_offset=None, before_offset=None, meta_constraints=None, limit=100, skip=0, exclude_export_to=None, exclude_imported=False)[source]¶

Encapsulates the possible parameters which can be used to search for meteorpi_model.FileRecord instances

__init__(camera_ids=None, lat_min=None, lat_max=None, long_min=None, long_max=None, after=None, before=None, mime_type=None, semantic_type=None, exclude_events=False, after_offset=None, before_offset=None, meta_constraints=None, limit=100, skip=0, exclude_export_to=None, exclude_imported=False)[source]¶

Create a new FileRecordSearch. All parameters are optional, a default search will be created which returns at most the first 100 FileRecord instances. All parameters specify restrictions on these results.

Parameters:

camera_ids (list[string]) – Optional - if specified, restricts results to only those the the specified camera IDs which are expressed as an array of strings. lat_min (float) – Optional - if specified, only returns results where the camera status at the time of the file had a latitude field of at least the specified value. lat_max (float) – Optional - if specified, only returns results where the camera status at the time of the file had a latitude field of at most the specified value. long_min (float) – Optional - if specified, only returns results where the camera status at the time of the file had a longitude field of at least the specified value. long_max (float) – Optional - if specified, only returns results where the camera status at the time of the file had a longitude field of at most the specified value. after (datetime.datetime) – Optional - if specified, only returns results where the file time is after the specified value. before (datetime.datetime) – Optional - if specified, only returns results where the file time is before the specified value. mime_type (string) – Optional - if specified, only returns results where the MIME type exactly matches the specified value. semantic_type (NSString) – Optional - if specified, only returns results where the semantic type exactly matches. The type of this value should be an instance of meteorpi_model.NSString exclude_events (Boolean) – Optional - if True then files associated with an meteorpi_model.Event will be excluded from the results, otherwise files will be included whether they are associated with an Event or not. after_offset (int) – Optional - if specified this defines a lower bound on the time of day of the file time, irrespective of the date of the file. This can be used to e.g. only return files which were produced after 2am on any given day. Specified as seconds since the previous mid-day. before_offset (int) – Optional - interpreted in a similar manner to after_offset but specifies an upper bound. Use both in the same query to filter for a particular range, i.e. 2am to 4am on any day. meta_constraints (list[MetaConstraint]) – Optional - a list of meteorpi_model.MetaConstraint objects providing restrictions over the file record metadata. limit (int) – Optional, defaults to 100 - controls the maximum number of results that will be returned by this search. If set to 0 will return all results, but be aware that this may potentially have negative effects on the server software. Only set this to 0 when you are sure that you won’t return too many results! skip (int) – Optional, defaults to 0 - used with the limit parameter, this will skip the specified number of results from the result set. Use when limiting the number returned by each query to paginate the results, i.e. use skip 0 and limit 10 to get the first ten, then skip 10 limit 10 to get the next and so on. exclude_export_to (uuid.UUID) – Optional, if specified excludes FileRecords with an entry in t_fileExport for the specified file export configuration. Note that this only applies to files which are not part of an event, so it only makes sense to set this flag if you also set exclude_events to True. exclude_imported (Boolean) – Optional, if True excludes any FileRecords which were imported from another node. Note that this only applies to files which are not part of an event, so it only makes sense to set this flag if you also set exclude_events to True.

EventSearch¶

class meteorpi_model.EventSearch(camera_ids=None, lat_min=None, lat_max=None, long_min=None, long_max=None, after=None, before=None, after_offset=None, before_offset=None, event_type=None, meta_constraints=None, limit=100, skip=0, exclude_export_to=None, exclude_imported=False)[source]¶

Encapsulates the possible parameters which can be used to search for Event instances in the database. If parameters are set to None this means they won’t be used to restrict the possible set of results.

__init__(camera_ids=None, lat_min=None, lat_max=None, long_min=None, long_max=None, after=None, before=None, after_offset=None, before_offset=None, event_type=None, meta_constraints=None, limit=100, skip=0, exclude_export_to=None, exclude_imported=False)[source]¶

Create a new EventSearch. All parameters are optional, a default search will be created which returns at most the first 100 Event instances. All parameters specify restrictions on these results.

Parameters:

camera_ids (list[string]) – Optional - if specified, restricts results to only those the the specified camera IDs which are expressed as an array of strings. lat_min (float) – Optional - if specified, only returns results where the camera status at the time of the event had a latitude field of at least the specified value. lat_max (float) – Optional - if specified, only returns results where the camera status at the time of the event had a latitude field of at most the specified value. long_min (float) – Optional - if specified, only returns results where the camera status at the time of the event had a longitude field of at least the specified value. long_max (float) – Optional - if specified, only returns results where the camera status at the time of the event had a longitude field of at most the specified value. after (datetime.datetime) – Optional - if specified, only returns results where the event time is after the specified value. before (datetime.datetime) – Optional - if specified, only returns results where the event time is before the specified value. semantic_type (NSString) – Optional - if specified, only returns results where the semantic type exactly matches. after_offset (int) – Optional - if specified this defines a lower bound on the time of day of the event time, irrespective of the date of the file. This can be used to e.g. only return events which were produced after 2am on any given day. Specified as seconds since the previous mid-day. before_offset (int) – Optional - interpreted in a similar manner to after_offset but specifies an upper bound. Use both in the same query to filter for a particular range, i.e. 2am to 4am on any day. meta_constraints (list[MetaConstraint]) – Optional - a list of meteorpi_model.MetaConstraint objects providing restrictions over the event metadata. limit (int) – Optional, defaults to 100 - controls the maximum number of results that will be returned by this search. If set to 0 will return all results, but be aware that this may potentially have negative effects on the server software. Only set this to 0 when you are sure that you won’t return too many results! skip (int) – Optional, defaults to 0 - used with the limit parameter, this will skip the specified number of results from the result set. Use when limiting the number returned by each query to paginate the results, i.e. use skip 0 and limit 10 to get the first ten, then skip 10 limit 10 to get the next and so on. exclude_export_to (uuid.UUID) – Optional, if specified excludes Events with an entry in t_eventExport for the specified event export configuration. Note that this only applies to files which are not part of an event, so it only makes sense to set this flag if you also set exclude_events to True. exclude_imported (Boolean) – Optional, if True excludes any Events which were imported from another node.

MetaConstraint¶

class meteorpi_model.MetaConstraint(constraint_type, key, value)[source]¶

Defines a constraint over metadata on a FileRecord or Event, used in the respective searches.

__init__(constraint_type, key, value)[source]¶

Constructor

Parameters:

constraint_type (string) – one of ‘before’, ‘after’, ‘string_equals’, ‘number_equals’, ‘less’, ‘greater’ key (NSString) – an meteorpi_model.NSString containing the namespace prefixed string to use as a key value (object) – the value, for string_equals this is a String, for ‘before’ and ‘after’ it’s a datetime.datetime and for ‘less’, ‘greater’ and ‘number_equals’ a number (generally a float or int).

NSString¶

class meteorpi_model.NSString(s, ns='meteorpi')[source]¶

Namespace prefixed string, with the namespace defaulting to ‘meteorpi’.

These are used in various places within the model where we want to specify names but avoid potential collisions. In general NSString instances prefixed by ‘meteorpi’ are official keys provided by the core project team. In the future users and third parties may extend the available metadata etc. and would use this mechanism to put all their extension elements into their own namespace, thus avoiding any potential issues with overlapping names.

Variables:	ns (string) – string namespace, defaults to ‘meteorpi’. Must not be None, the empty string, or contain the ‘:’ character. s (string) – string part, can be any value. Must not be None.

__init__(s, ns='meteorpi')[source]¶

Create a new namespaced string

Parameters:	s (string) – The value part of the namespaced string object. ns (string) – The namespace, optional, defaults to ‘meteorpi’ if not specified.

static from_string(s)[source]¶

Strings are stored as ns:s in the database, this method parses them back to NSString instances

User¶

class meteorpi_model.User(user_id, role_mask)[source]¶

A single user in an instance of the MeteorPi server

Class variables:

Variables:

roles (list[string]) – A sequence of roles, the ordering of items in this sequence is meaningful and must not be changed, new values may be appended. The current values, in order, are: user: the user can log in, no other permissions camera_admin: the user can manipulate the editable parts of CameraStatus, vis. the installation url and name, and the visible region polygons. import: the user can import data into this node, used to manage from which parties data can be received during import / export operations.

Instance variables:

Variables:	user_id (string) – a string ID for the user role_mask (int) – an integer bit-mask defining the available roles for the user

__init__(user_id, role_mask)[source]¶

get_roles()[source]¶

Returns:	A sequence of strings, each string being a role that the user can access

has_role(role)[source]¶

Determine whether the user has a given role

Parameters:	role (string) – The role to test
Returns:	True if the user can act in that role, False otherwise

static role_mask_from_roles(r)[source]¶

Get a role_mask bit-mask from a sequence of strings, the string values must correspond to roles in User.roles

Parameters:	r (list[string]) – A sequence of string role-names
Returns:	A role_mask which can be used to concisely store the roles.

static roles_from_role_mask(rm)[source]¶

Get a list of roles for a given role_mask

Parameters:	rm (int) – An integer interpreted as a bit-mask
Returns:	A list of strings containing roles corresponding to the supplied mask

CameraStatus¶

class meteorpi_model.CameraStatus(lens, sensor, inst_url, inst_name, orientation, location, camera_id, status_id=None)[source]¶

Represents the status of a single camera for a range of times.

The status is valid from the given validFrom datetime (inclusively), and up until before the given validTo datetime; if this is None then the status is current.

Variables:

lens (string) – Name of the camera lens in use. This must match the name field of an entry in <sensorProperties/lenses.xml> sensor (string) – Name of the camera in use. This must match the name field of an entry in <sensorProperties/sensors.xml> inst_name (string) – Installation name, e.g. “Cambridge Secondary School, South Camera” inst_url (string) – Web address associated with installation, e.g. the school’s website orientation (Orientation) – An instance of meteorpi_model.Orientation describing the orientation of the camera. location (Location) – An instance of meteorpi_model.Location describing the location (including potential uncertainty) of the camera. software_version (int) – Integer version number of the software stack on the camera node regions (list[dict]) – List of list of dictionaries of the form {‘x’:x,’y’:y}. The points in each list describe a polygon within which camera can see the sky. Coordinates are in image space, so the origin at 0,0 is at the top left as viewed on the screen, and values are pixels. valid_from (datetime.datetime) – datetime object representing the earliest date of observation from which this camera status is valid valid_to (datetime.datetime) – datetime object representing the latest date of observation for which this camera status is valid

__init__(lens, sensor, inst_url, inst_name, orientation, location, camera_id, status_id=None)[source]¶

class meteorpi_model.Location(latitude=0.0, longitude=0.0, gps=False, error=0.0)[source]¶

A location fix, consisting of latitude and longitude, and a boolean to indicate whether the fix had a GPS lock or not.

Variables:

latitude (float) – Latitude of the camera installation, measured in degrees. Positive angles are north of equator, negative angles are south. longitude (float) – Longitude of the camera installation, measured in degrees. Positive angles are east of Greenwich, negative angles are west. gps (boolean) – True if the location was identified by GPS, False otherwise. error (float) – Estimate of error in longitude and latitude values, expressed in meters.

__init__(latitude=0.0, longitude=0.0, gps=False, error=0.0)[source]¶

class meteorpi_model.Orientation(altitude=0.0, azimuth=0.0, error=0.0, rotation=0.0, width_of_field=0.0)[source]¶

An orientation fix, consisting of altitude, azimuth, certainty.

The angles, including the error, are floating point quantities with degrees as the unit. These values are computed from astrometry.net, so use documentation there as supporting material when interpreting instances of this class.

Variables:

altitude (float) – Angle above the horizon of the centre of the camera’s field of view. 0 means camera is pointing horizontally, 90 means camera is pointing vertically upwards. azimuth (float) – Bearing of the centre of the camera’s field of view, measured eastwards from north. 0 means camera pointing north, 90 east, 180 south, 270 west. rotation (float) – Position angle of camera’s field of view (measured at centre of frame). 0 = celestial north up, 90 = celestial east up, 270 = celestial west up. error (float) – Estimate of likely error in altitude, azimuth and rotation values, expressed in degrees. width_of_field (float) – For a frame of dimensions (w,h), the angular distance between the pixels (0,h/2) and (w/2,h/2). That is, half the angular width of the frame.

__init__(altitude=0.0, azimuth=0.0, error=0.0, rotation=0.0, width_of_field=0.0)[source]¶

Export¶

These classes are used to configure the data export mechanism within a node, it’s unlikely you’ll need to use them directly yourself but they’re part of the model API so included here for completeness.

class meteorpi_model.ExportConfiguration(target_url, user_id, password, search, name, description, enabled=False, config_id=None)[source]¶

Defines an export configuration, comprising an meteorpi_model.EventSearch or meteorpi_model.FileRecordSearch defining a set of meteorpi_model.Event or meteorpi_model.FileRecord objects respectively which should be exported, and the necessary information about the target, including its URL, user and password. Also carries a descriptive name and long description for management and a UUID for the configuration itself.

Variables:

config_id (uuid.UUID) – The external ID for this export configuration target_url (string) – The root URL of the importing API to which data should be pushed user_id (string) – The user ID that should be supplied as an auth header when pushing data to the importing API password (string) – The password that should be supplied as an auth header when pushing data to the importing API search (EventSearch|FileRecordSearch) – An class:meteorpi_model.EventSearch or class:meteorpi_model.FileRecordSearch which defines the meteorpi_model.Event or meteorpi_model.FileRecord instances to export. Note that there are some properties of the search which will be overridden by the export system, most particularly searches will have exclude_incomplete and exclude_export_to set to True and the ID of this configuration so we don’t create duplicate export jobs for any given target. FileRecordSearch instances will also additionally have their ‘exclude_events’ flag set, as file record exports only handle independent files and not those associated with an event. name (string) – Short name for this export configuration description (string) – A longer free text description for this configuration enabled (Boolean) – True if this export configuration is enabled, False otherwise. type (string) – Set based on the type of the supplied search object, either to ‘file’ or ‘event’.

__init__(target_url, user_id, password, search, name, description, enabled=False, config_id=None)[source]¶