The processor interface within Speckle admin allows you to run operations on Speckle objects, streams, and projects from within the web application.
Each processor is composed of blocks. By assembling a series of simple blocks together, a complex sequence of operations can be performed. Each block takes the input of the previous block, passes it through a function, and returns the output for further use. Note that you do not need any programming knowledge to use processor, only to add new blocks to it.
Creating your first processor
Our first processor will take a stream, filter its objects based on its proximity to a location, and create a new stream based on these objects.
To start, create a new processor by pressing the blue + button in the lower right corner of the processor page. You will then be taken to the processor details page. From here, you can change its name, add tags, create a description, share you processor, and assemble your blocks.
Using the add new block list box, you can select a new block to add to your processor. You can delete blocks by clicking on the button on the top left of each block.
For our processor, we will use the following built in blocks:
- Speckle Stream Receiver: returns the ID of the objects contained in the streams.
- Download Speckle Objects: gets the objects from the ID given in the input.
- Proximity Filter: filters objects based on its distance from a point.
- Upload Speckle Objects: creates new Speckle objects in the server from the input. This is needed when you modify objects which you have received from a stream. Returns a list of ID of the objects which was uploaded.
- Speckle Stream Sender: creates a new stream based on the list of object IDs.
Once added, the parameters for the input can be added. For this doc, we will be using stream
LqyefJKXG found on the Hestia server containing some boxes in 3D space. For the inputs of our proximity filter, we will take all objects within a 10 unit radius from the point (0, 0, 0).
To run the processor, click the blue play buttom on the bottom right. As the processor is running, you can see the output of each intermediate step by clicking on the view output button below each block. The output of the full processor is displayed at the bottom of the page. In our case, the output will be the stream ID.
To rerun, click the blue button on the bottom right again. You can also choose to rerun from a specific block by clicking the re-run button on that block. Processor will also automatically detect when you make changes to a block and un-runs any blocks affected by the change.
You have now successfully created and ran your first processor. To see the results of the processor, you can view stream
rVrsg-FDi found on the Hestia server.
Writing your own blocks
To write your own block, you will only need to create a lambda function for the Speckle admin and add your function to the list of loaded functions here. Each function needs to support both GET and POST API calls:
- The GET API call will return information regarding the function:
name: name of block
description: description of block
icon: material icon description
allowBucketing: boolean flag which indicates whether the function call can be split. This only works if the input is an array.
customComponent: boolean flag which allows for custom UI as opposed to the default generated UI
parameters: array of parameters which users can add from the UI. Each parameter object has a name and type property.
- The POST API call will take the inputs of the previous block and perform the required operations. The function's body parameter will contain four fields:
baseURL: base URL of the server
token: Speckle server access token
input: input from the previous block
parameters: user input parameters from the UI.
Processor will automatically generate the UI given the body of the GET API call. It is possible to override the UI of the block (see here for an example). The vue component must take two properties:
block: the body of the GET request
params: an object who's keys are the block parameter names and the value is the input which will be passed to the lambda function when run
Additionally, it is the responsibility of the component to emit an
update-param event when a value in the
params object is updated.
For examples of lambda functions, please see the GitHub source code.