Datasets, Groups and users

Specklia is divided up into Datasets, Groups and Users. This section explains what each of these things are, and how they interact.

User IDs

Each user has a unique ID, which can be obtained from the client using the Specklia.user_id property.

This user ID is the correct way to uniquely identify yourself to other Specklia users, or to Earthwave. It’s a little clunkier than a name or an email, but it has the advantage that Earthwave cannot uniquely identify users and profit from selling their data to third parties. See our privacy policy for further details.

Datasets

Data is stored within Specklia in datasets. Each dataset is a large collection of points with pre-defined fields. You can list all of the datasets that you currently have the ability to query using Specklia.list_datasets(). The geometry and timestamp fields are mandatory. Other custom fields can be defined when the dataset is created.

Datasets must first be created, and then have data added to them (i.e. uploaded / ingested). Datasets are created using Specklia.create_dataset(). Once a dataset has been created, points can be added to it using Specklia.add_points_to_dataset(). To delete a dataset from Specklia, using Specklia.delete_dataset().

It is not currently possible to update and delete specific points within a dataset. We will be adding these capabilities soon.

Datasets can be queried using Specklia.query_dataset(). Note that querying a large area / duration is likely to take a long time, and may fail due to various timeouts built into Specklia.

Groups

Specklia is divided up into Groups. Groups are intended to allow users to share data amongst themselves. Each group has a name, contains one or more users, and contains one or more datasets. A specklia user can list all of the groups they are currently a member of using Specklia.list_groups()

There are two special kinds of groups. Firstly, every user is a member of a group named after their user ID. This is their “personal group”. Every dataset that a user uploads to Specklia starts off in their personal group, and must be moved into other groups from there. Secondly, every user is a member of a special group called all_users. Datasets within the all_users group are therefore accessible by all Specklia users.

Beyond personal groups and the all_users group, Specklia users are free to create, manipulate and destroy groups as they see fit. Groups are created using Specklia.create_group(), renamed using Specklia.change_group_name() and deleted using Specklia.delete_group().

Once a group exists, datasets can be added and removed using Specklia.update_dataset_ownership(). Note that all datasets belong to exactly one group at all times.

Users can be added to and removed from a group using Specklia.add_user_to_group() and Specklia.delete_user_from_group().

Permissions within Groups

Specklia features permissions management in order to allow individuals to upload and distribute private datasets. There are three levels of permissions: READ_ONLY, READ_WRITE and ADMIN.

Permissions are implemented at the level of users and groups. For example, a notional user ‘Charlie’ will have by default:

ADMIN permissions within Charlie’s personal group.
READ_ONLY permissions within the all_users group.

If Charlie is invited to a different Specklia group, Charlie will start off in that group with READ_ONLY permissions. Anyone who has ADMIN permissions within that group can then change Charlie’s permissions.

Users with READ_ONLY permissions in a group are able to query datasets within that group, but do nothing more.
Users with READ_WRITE permissions in a group can add data to and delete data from datasets within that group. They are not able to add whole datasets to the group, or remove them from the group.
Users with ADMIN permissions in a group are able to do anything to any dataset within that group, including adding and removing datasets and users.

Once a user has been added to a group using Specklia.add_user_to_group(), their permissions can be set by any of the group’s admins using Specklia.set_user_privileges(). The group’s admins can use Specklia.list_users() to list all of the users within a group, along with their permissions.