Recipe schema v2.0

The recipe JSON file defines the specification for a cellPACK packing, including the ingredients to be packed, their spatial relationships, and composition hierarchy.

Settings

The top-level fields include metadata about the recipe, such as its name, version, and bounding box. It also specifies the file path for grid data.

Field Path	Type	Description	Default Value	Notes
name	string	Name of the recipe
version	string	Recipe version string	“default”	Version of the recipe is appended to the output file name.
format_version	string	Schema format version	“1.0”	Older recipe formats do not have this field. Recipes are automatically migrated to the latest format version before packing.
bounding_box	array [[minX, minY, minZ], [maxX, maxY, maxZ]]	Bounding box of the packing result	[[ 0, 0, 0 ], [ 100, 100, 100 ]]
grid_file_path	string	File path to read/write grid data		If not specified, a grid file is created and stored at the output path.

Example:

{
    "name": "one_sphere",
    "version": "1.0.0",
    "format_version": "2.0",
    "bounding_box": [
        [
            0,
            0,
            0
        ],
        [
            20,
            20,
            20
        ]
    ],
    "grid_file_path": "/path/to/local/file" // optional
    ...[OTHER_SETTINGS],
}

Recipe.objects

This section contains information about the objects to be packed, including their types, colors, sizes, and packing methods. Each object can inherit properties from another object.

Field Path	Type	Description	Default Value	Notes
color	array (RGB 0–1) [float, float, float]	RGB color of object
type	string (enum)	Object type	single_sphere	Accepts a type from "single_sphere", "multi_sphere", "single_cube", "single_cylinder", "multi_cylinder", "grow", mesh
inherit	string	Linked name of the inherited object		Defined by the object. Must exist in objects
radius	number	Object radius
jitter_attempts	number	Max retries for packing	5
max_jitter	array (0–1 per axis)	Vector with maximum jitter distance in units of grid spacing	[1, 1, 1]
place_method	string(enum)	Method used for packing the object	jitter	Accepts a method from jitter, spheresSST. Can be overwritten by a global config.
available_regions	array	Regions where the object can be placed		e.g. interior, surface, outer_leaflet, inner_leaflet
packing_mode	string(enum)	Packing behavior mode	random	Tied to the recipe. Accepts a packing mode from random, close, closePartner, randomPartner, gradient, hexatile, squaretile, triangletile
gradient	string or list of strings	Gradient(s) applied to object		Must exist in gradients
representations.mesh.path	string	Mesh file path
representations.mesh.name	string	Mesh file name		Tied to the object
representations.mesh.format	string	Mesh file format		Tied to the object
representations.mesh.coordinate_system	string (left or right)	Depends on generating software	left
partners.names	array(string[])	List of partner object names		Objects that attract to this one, must exist in objects
partners.probability_binding	number (0–1)	Probability of binding with partners	0.5
partners.positions	array	Partner relative positions		Relative positions for partner placement
partners.excluded_names	array(string[])	List of excluded partner objects		Objects that repel from this one
partners.probability_repelled	number (0–1)	Probability of repulsion from excluded partners
partners.weight	number	Weight factor for partner interactions	0.2	Influence strength of partner effects

Example:

...[OTHER_SETTINGS],
"objects": {
    "base": {
        "jitter_attempts": 10,
        "rotation_range": 6.2831,
        "cutoff_boundary": 0,
        "max_jitter": [
            0.2,
            0.2,
            0.01
        ],
        "perturb_axis_amplitude": 0.1,
        "packing_mode": "random",
        "principal_vector": [
            0,
            0,
            1
        ],
        "rejection_threshold": 50,
        "place_method": "spheresSST",
        "cutoff_surface": 42,
        "rotation_axis": [
            0,
            0,
            1
        ],
        "available_regions": {
            "interior": {},
            "surface": {},
            "outer_leaflet": {},
            "inner_leaflet": {}
        }
    },
    "sphere_25": {
        "type": "single_sphere",
        "inherit": "base",
        "color": [
            0.5,
            0.5,
            0.5
        ],
        "radius": 5,
        "max_jitter": [
            1,
            1,
            0
        ],
        "representations": {
            "mesh": {
                "path": "path/to/local/folder/",
                "name": "mesh.obj",
                "format": "obj"
            }
        }
    }
}

Recipe.gradients

Field Path	Type	Description	Default Value	Notes
description	string	Description of gradient
mode	string(enum)	Type of gradient	“X”	Defined by gradient. Accepts a mode from "x", "y", "z", "vector", "radial", "surface"
pick_mode	string(enum)	Gradient sampling method	"linear"	Accepts a pick mode from "max", "min", "rnd", "linear", "binary", "sub", "reg"
weight_mode	string(enum)	Modulates the form of the grid point weight dropoff		Accepts a weight mode from "linear", "square", "cube", "power", "exponential"
reversed	boolean	Reverse gradient direction
invert	boolean	Invert gradient weights
weight_mode_settings.decay_length	number	Decay rate parameter		Controls gradient falloff
mode_settings.object	string	Reference object for gradient		Links to a mesh object
mode_settings.scale_to_next_surface	boolean	Scaling toggle
mode_settings.direction	array [x, y, z]	Direction vector for mode		Defined by the mode
mode_settings.center	array [x, y, z]	Center point for the gradient		Used as the origin for radial or directional gradients, defined by the mode

Example:

...[OTHER_SETTINGS],
"gradients": {
    "nucleus_gradient": {
        "description": "gradient based on distance from the surface of the nucleus mesh",
        "mode": "surface",
        "mode_settings": {
            "object": "nucleus",
            "scale_to_next_surface": false
        },
        "weight_mode": "exponential",
        "weight_mode_settings": {
            "decay_length": 0.1
        }
    }
}

Recipe.composition

The composition section defines the hierarchical structure of containers and their contents. It establishes parent-child relationships between objects and specifies which objects are placed within different regions.

Field Path	Type	Description	Default Value	Notes
id	string (unique)	Unique identifier for the composition item		Must be unique within composition
object	string	Linked object name		Must exist in objects
count	number (integers >= 0)	Number of objects	5	Falls back to definition in the object section
priority	number	Packing priority		e.g. -1
regions.interior	array	Interior contents of object
regions.surface	array	Surface contents of object		Objects placed on the surface
regions.inner-leaflet	array	Inner leaflet contents		Objects placed on inner leaflet
regions.outer-leaflet	array	Outer leaflet contents		Objects placed on outer leaflet

Example:

...[OTHER_SETTINGS],
"composition": {
    "bounding_area": {
        "regions": {
            "interior": [
                "outer_sphere",
                {
                    "object": "green_sphere",
                    "count": 5
                }
            ]
        }
    },
    "outer_sphere": {
        "object": "large_sphere",
        "count": 1,
        "regions": {
            "interior": [
                "inner_sphere",
                {
                    "object": "red_sphere",
                    "count": 40
                }
            ],
            "surface": [{
                "object": "green_sphere",
                "count": 40
            }]
        }
    },
    "inner_sphere": {
        "object": "medium_sphere",
        "regions": {
            "interior": [
                {
                    "object": "green_sphere",
                    "count": 20
                }
            ]
        }
    }
}