Getting Started

Get up and running with Steno3D! This page contains resources for installing Steno3D, trying out a sample project yourself, and exploring public projects.

If you run into issues: report them on github.

Install Steno3D

Want to start using Steno3D with your own data? It is available on pip:

pip install steno3d

or install from source:

git clone https://github.com/3ptscience/steno3dpy.git
python setup.py install

Example Jupyter notebooks can be cloned or you can follow along online with the First Project below

git clone https://github.com/3ptscience/steno3d-notebooks.git

A First Project

Let’s get started using Steno3D. The following demo project is available online in a Jupyter notebook at mybinder.org, no installation required.

Here, we will create a public project containing a surface, upload it, and explore it with Steno3D!

../_images/steno3dpy_screenshot.png

Start by importing Steno3D. If you are using the online notebooks your environment should already be set up; otherwise, Steno3D is easy to install.

>> import steno3d

Log In

Next, you need to login using your API developer key. If you do not have a Steno3D account, you can sign up and request a developer key associated with your account.

Then, login using this key within Python. You need to do this step even if you are logged in to steno3d.com; the developer key and your website login are separate.

>> steno3d.login('this-is-a-demo-key')

Note

By default, your developer key will be saved locally to default credentials file ~/.steno3d_client/credentials. This allows future logins without manually entering your key:

>> steno3d.login()

You may specify a different credentials file with:

>> steno3d.login('this-is-a-demo-key', credentials_file='/path/to/file')

or you may opt to not save the developer key at all with:

>> steno3d.login('this-is-a-demo-key', skip_credentials=True)

If you ever lose your key, you can always generate a new one.

Create Resources

We start by creating a project

>> my_proj = steno3d.Project(
       title='Demo Project',
       description='My first project',
       public=True
   )

Here, we will create a topographic surface of a sinc function. We will use numpy to do this.

>> import numpy as np
>> topo = lambda X, Y: 50*np.sinc(np.sqrt(X**2. + Y**2.)/20.)

Next, we define our x and y coordinates to make the mesh

>> x = np.linspace(-100, 100., num=100.)
>> y = np.linspace(-100., 100., num=100.)
>> my_mesh = steno3d.Mesh2DGrid(
       h1=np.diff(x),
       h2=np.diff(y),
       O=np.r_[-100.,-100.,0.]
   )

and define the Z vertex topography of the mesh.

>> X, Y = np.meshgrid(x, y, indexing='ij')
>> Z = topo(X, Y)
>> my_mesh.Z = Z.flatten()

Right now, we have a 2D mesh. Let’s create a surface with this mesh geometry.

>> my_surf = steno3d.Surface(
       project=my_proj,
       mesh=my_mesh
   )
>> my_surf.title = 'Sinc Surface'
>> my_surf.description = '3D rendering of sinc function in Steno3D'

You may want to put data on the mesh. In this case, we assign topography (same as the Z-values of the mesh) as data on the nodes of the mesh

>> my_topo_data = steno3d.DataArray(
       title='Sinc function topography',
       array=my_mesh.Z
   )
>> my_surf.data = [dict(
       location='N',
       data=my_topo_data
   )]

Upload

In order to view our 3D data, we first need to upload it. Prior to uploading, you can check that all required parameters are set and valid

>> my_surf.validate()

and then upload the surface.

>> my_surf.upload()

This will return a URL where you can view it.

View

There are two options for viewing, if you are using the Jupyter notebook you can plot the surface inline. This allows you to inspect it and make sure it is constructed correctly.

>> my_surf.plot()

Once you are happy with your upload, use the project URL to view, explore, and share the project on steno3d.com.

>> print(my_proj.url)

Explore Steno3D

To give you a flavor of Steno3D’s capabilities, you can explore public Steno3D projects

../_images/steno3d_explore.png