API Integration Guide

SplineCloud incorporates a unique hierarchical data structure to effectively manage data repositories, data sources (data files), their clean representations (subsets), and functional relations constructed using the interactive curve fitting tool. This guide explains the main cases for loading and working with spline curves and subsets in your code. For a detailed API reference visit the SplineCloud API documentation page.

Repository

The repository is the top-level container in the SplineCloud hierarchy. It serves as an organizational unit for related data files and can represent a project, research area, or collection of related work. Each Repository has a unique identifier (UID) that starts with the 'rpo' prefix.

DataFile

A DataFile object is essentially a reference to the repository files. Each DataFile can contain multiple Dataset objects, allowing you to organize your raw data sources within a repository: define datasets on image plots, name and add metadata to the sheets of spreadsheets, etc. The DataFile object represents the source of your data, which may contain experimental results, simulation outputs, or collected measurements. brief article, you will get a picture of how to digitize graphical data with our free online plot digitizer. Each DataFile has a unique identifier (UID) that starts with the 'dfl' prefix.

Dataset

Each Dataset belongs to a specific DataFile and can contain multiple Subsets. Datasets serve as a definition of where to read data from the file: for graphical data, they represent a coordinate system of the graphs, for spreadsheets - a sheet that contains data. Each dataset can have associated metadata - name, units used in data headers, and user-provided description. Each Dataset has a unique identifier (UID) that starts with the 'dst' prefix.

Subset

A Subset represents a clean, processed data table derived from a Dataset. Subsets contain the actual numerical data of interest in a structured format. For example, Subsets may represent a selection of rows and columns on the data table, or a range of points on the plot. Each Subset can have multiple DataRelations. Each Subset has a unique identifier (UID) that starts with the 'sbt' prefix.

DataRelation

A DataRelation object maps the relationship between one variable to another within a Subset (one column to another). For example, a DataRelation might define how the lift coefficient relates to the angle of attack. Each DataRelation can have multiple SplineCurves associated with it, though typically one is sufficient for most applications. Each DataRelation has a unique identifier (UID) that starts with the 'drl' prefix.

SplineCurve

A SplineCurve is the mathematical representation of a DataRelation using spline interpolation techniques. These curves provide smooth, continuous functions that can be evaluated at any point and used in computational models. SplineCurves are the primary objects that users typically access and utilize through the API. Each SplineCurve has a unique identifier (UID) that starts with the 'spl' prefix.

---

The typical Curve endpoint follows this pattern: https://splinecloud.com/ api/curves/<curve_uid>
where <curve_uid> is a unique identifier of the curve, which can be found on the API link drop-down window on the Curves toolbar.

Any spline curve (NURBS curve) is represented by the next parameters:

• order, k: integer
• knot vector, t: array of the float type numbers
• control points, c: array of the pairs of the float type
• weights of control points, w: array of integers

This data is available in the response to the curve API call:

curl https://splinecloud.com/api/curves/spl_K5t56P5bormJ/

{
    "uid": "spl_K5t56P5bormJ",
    "name": "Spline Curve 1",
    "curve_type": "smooth-bspl",
    "order": 2,
    "spline": {
        "c": [
            [
                0.11575824266706314,
                0.13036447023210782
            ],
            [
                2.666062701476161,
                0.4425709138967927
            ],
            [
                7.913559084732197,
                0.9822488834378817
            ],
            [
                12.554707389140184,
                1.4061897021758403
            ],
            [
                15.997526418229713,
                1.4179718680623563
            ],
            [
                17.496389067358194,
                1.2830615476024234
            ]
        ],
        "k": 2,
        "t": [
            0.0,
            0.0,
            0.0,
            0.2934651204012808,
            0.6038326728396279,
            0.8275249426506224,
            1.0,
            1.0,
            1.0
        ],
        "w": [
            1,
            1,
            1,
            1,
            1,
            1
        ]
    },
    "labels": {
        "xlabel": "AoA (deg.)",
        "ylabel": "cl"
    },
    "relation_uid": "drl_788FVjNujErE",
    "subset_uid": "sbt_iu0hd3vEvQpd"
}
        

The same parameters are also available in a curve details drop-down window. .

---

With SplineCurve data, you can reconstruct spline curves (NURBS curves) in your favorite programming language or computer math system and reuse them in your models as regular functions. There are numerous libraries available for building and evaluating NURBS curves. However, it is more convenient to use SplineCloud client libraries

Python Client

Install the official Python client from PyPI:

pip install splinecloud-scipy

Here's a simple example of how to fetch and evaluate spline curves using splinecloud-scipy:

import numpy as np
import matplotlib.pyplot as plt
import splinecloud_scipy as sc

# Fetch a curve by its UID
spline = sc.load_spline('spl_K5t56P5bormJ')

# Evaluate points on the curve
X = np.linspace(0, 20, 100)
Y = [spline.eval(x) for x in X]

# Plot the curve
plt.plot(X,Y)
plt.grid()
plt.show()
        

You can also load the underlying data used to construct the spline curve:

columns, table = spline.load_data()
x_data, y_data = table.T

plt.plot(X,Y)
plt.plot(x_data, y_data, 'o', color="grey")
plt.grid()
plt.xlabel(columns[0])
plt.ylabel(columns[1])
plt.show()
        

The client library for Python also allows to evaluate fit accuracy using Root Mean Square Error (RMSE) or Mean Square Error (MSE) estimators.

RMSE = spline.fit_accuracy(table, method="RMSE")
print(RMSE)

0.011307453345329156
        

MATLAB Client

The MATLAB client is currently under development, but you can already use the development version:

clear variables; clear all; cc;

addpath(genpath('splinecloud-matlab'));

curveId = 'spl_BUDRcYh1Mbvy';

spline = fetchCurve(curveId);

[ctrlPoints, knots] = extractNurbsParams(spline);

nurbs = nrbmak(ctrlPoints, knots);

xPoints = linspace(0, 5, 100);
xLength = length(xPoints); 
yPoints = zeros(1, xLength);

for i = 1:xLength
    yPoints(i) = getYByX(nurbs, xPoints(i));
end

plot(xPoints, yPoints);
            

---

The typical Subset endpoint follows this pattern: https://splinecloud.com/ api/subsets/<subset_uid>
where <subset_uid> is a unique identifier of the subset, which can be found on the API link drop-down window on the Subsets toolbar.

{
    "uid": "sbt_nDO4XmmYqeGI",
    "name": "Subset 1",
    "author": {
        "id": 22,
        "username": "Serhii.K"
    },
    "dataset": {
        "uid": "dst_jrkyAqWBokzT",
        "name": "24V_Propeller_5030-3P",
        "local_id": 0,
        "last_modified": "2025-02-02T10:29:58.925117Z",
        "author": {
            "id": 22,
            "username": "Serhii.K"
        },
        "datafile": {
            "uid": "dfl_PVtDZpMA90aF",
            "name": "XING2 1806 FPV_KV2500_Test_Report.xlsx",
            "last_modified": "2025-02-02T10:29:45.093648Z",
            "path": "XING2_Motors/XING2 1806 FPV/XING2 1806 FPV_KV2500/XING2 1806 FPV_KV2500_Test_Report.xlsx",
            "repo": {
                "uid": "rpo_GGFnRHlVnyoV",
                "name": "iFlight Drone Motors",
                "author": {
                    "id": 22,
                    "username": "Serhii.K"
                },
                "last_modified": "2025-03-24T00:00:17.883640Z"
            }
        }
    },
    "table": {
        "Throttle (%)": {
            "0": 0.5,
            "1": 0.6,
            "2": 0.7,
            "3": 0.8,
            "4": 0.9,
            "5": 1.0
        },
        "Load Currency (A)": {
            "0": 6.76,
            "1": 10.2,
            "2": 13.58,
            "3": 17.39,
            "4": 21.03,
            "5": 25.06
        },
        "Pull (g)": {
            "0": 385.0,
            "1": 495.0,
            "2": 606.0,
            "3": 687.0,
            "4": 747.0,
            "5": 807.0
        },
        "Power (W)": {
            "0": 108.71,
            "1": 162.49,
            "2": 217.68,
            "3": 271.4,
            "4": 328.13,
            "5": 385.55
        },
        "Efficiency (g/W)": {
            "0": 3.542,
            "1": 3.046,
            "2": 2.784,
            "3": 2.551,
            "4": 2.277,
            "5": 2.093
        }
    }
}
        

Python Client

If you need to access subsets only, you can use 'load_subset' method of the SplineCloud client library for Python, which returns a list of column names and a NumPy array with a data table:

from splinecloud_scipy import load_subset
subset_uid = 'sbt_nDO4XmmYqeGI' # subset uid can be taken from the SplineCloud
columns, table = load_subset(subset_uid)
            

>>> columns

['Throttle (%)',
'Load Currency (A)',
'Pull (g)',
'Power (W)',
'Efficiency (g/W)']
            

>>> table

array([[5.0000e-01, 6.7600e+00, 3.8500e+02, 1.0871e+02, 3.5420e+00],
    [6.0000e-01, 1.0200e+01, 4.9500e+02, 1.6249e+02, 3.0460e+00],
    [7.0000e-01, 1.3580e+01, 6.0600e+02, 2.1768e+02, 2.7840e+00],
    [8.0000e-01, 1.7390e+01, 6.8700e+02, 2.7140e+02, 2.5510e+00],
    [9.0000e-01, 2.1030e+01, 7.4700e+02, 3.2813e+02, 2.2770e+00],
    [1.0000e+00, 2.5060e+01, 8.0700e+02, 3.8555e+02, 2.0930e+00]])
            

The typical Datasets endpoint follows this pattern: https://splinecloud.com/ api/datasets/<dataset_uid>
where <dataset_uid> is a unique identifier of the dataset, which can be found on the API link drop-down window on the Datasets toolbar.

The main difference between Datasets and Subsets response, is that dataset may contain multiple subsets, so table data will be wrapped in the 'subsets' container in the response.

{
    "uid": "dst_jrkyAqWBokzT",
    "name": "24V_Propeller_5030-3P",
    "local_id": 0,
    "last_modified": "2025-02-02T10:29:58.925117Z",
    "author": {
        "id": 22,
        "username": "Serhii.K"
    },
    "datafile": {
        "uid": "dfl_PVtDZpMA90aF",
        "name": "XING2 1806 FPV_KV2500_Test_Report.xlsx",
        "last_modified": "2025-02-02T10:29:45.093648Z",
        "path": "XING2_Motors/XING2 1806 FPV/XING2 1806 FPV_KV2500/XING2 1806 FPV_KV2500_Test_Report.xlsx",
        "repo": {
            "uid": "rpo_GGFnRHlVnyoV",
            "name": "iFlight Drone Motors",
            "author": {
                "id": 22,
                "username": "Serhii.K"
            },
            "last_modified": "2025-03-24T00:00:17.883640Z"
        }
    },
    "subsets": [
        {
            "uid": "sbt_nDO4XmmYqeGI",
            "name": "Subset 1",
            "author": {
                "id": 22,
                "username": "Serhii.K"
            },
            "table": {
                "Throttle (%)": {
                    "0": 0.5,
                    "1": 0.6,
                    "2": 0.7,
                    "3": 0.8,
                    "4": 0.9,
                    "5": 1.0
                },
                "Load Currency (A)": {
                    "0": 6.76,
                    "1": 10.2,
                    "2": 13.58,
                    "3": 17.39,
                    "4": 21.03,
                    "5": 25.06
                },
                "Pull (g)": {
                    "0": 385.0,
                    "1": 495.0,
                    "2": 606.0,
                    "3": 687.0,
                    "4": 747.0,
                    "5": 807.0
                },
                "Power (W)": {
                    "0": 108.71,
                    "1": 162.49,
                    "2": 217.68,
                    "3": 271.4,
                    "4": 328.13,
                    "5": 385.55
                },
                "Efficiency (g/W)": {
                    "0": 3.542,
                    "1": 3.046,
                    "2": 2.784,
                    "3": 2.551,
                    "4": 2.277,
                    "5": 2.093
                }
            }
        }
    ],
    "subset_count": 1,
    "relation_count": 3
}
        

Python Client

As of now there is no support for the Datasets endpoint in the Python client, but this will be implemented soon.

Client libraries for other programming languages will enable smoother integration. Your contribution is welcome!
Drop us a message if you are interested in developing new or improving existing client libraries.