API Reference

Wiki ▸ API Reference

This is a preliminary version of the API documentation, on constant update as the library is developed. The complete library can be imported to a HTML document by simply referencing the build file:

<!--Import Vessel.js library-->
<script src="Vessel.js"></script>

Ship

This object joins instances of several classes and assembles a Ship, which represents the physical vessel and includes methods which account for it as an entire system. At the moment, those methods are mainly calculations of weight, draft and stability. A Ship object can be constructed as:

let ship = new Vessel.Ship(specification);

Where specification is an input specification such as these ones. The specification contains the following objects:

ship.attributes <> - lists attributes.
ship.baseObjects <> - various BaseObject instances containing the components which define the vessel.
ship.derivedObjects <> - various DerivedObject instances containing the components which define the vessel.
ship.designState <> - a ShipState object instance that determines default values for various state parameters, such as tank fillings.
ship.structure <> - a Structure object instance with information such as deck and bulkhead definitions.

Once constructed, the ship object inherits methods from the prototype.

Methods:

ship.calculateStability(shipState) <> - returns calculations for ship GM, KB, BM and KG.
ship.getSpecification() <> - returns an object with all specification data.
ship.getWeight(shipState) <> - returns the ship weight based on an input ship state. If none is provided, the method will use the ship's design state.
ship.setFromSpecification(specification) <> - fills ship properties with data from the specification.
ship.calculateDraft(shipState, epsilon=0.001, rho=1025) <> - returns the ship draft based on an input ship state. If none is provided, the method will use the ship's design state.

BaseObject

A base object is a ship physical component as it is fetched from the provided specification:

baseObjSpec: {
    "id": "baseTank",
    "boxDimensions": {
        "length": 10.25,
        "breadth": 9,
        "height": 1.6
    },
    "weightInformation": {
        "contentDensity": 850,
        "volumeCapacity": 145,
        "lightweight": 10000,
        "fullnessCGMapping": {...}
    },
    "baseState": {
        "fullness": 0.7
    },
    "affiliations": {},
    "capabilities": {}
};

Where:

affiliations - possible to include information related to the component's physical location or its SFI code.
baseState - default filling state for tanks.
boxDimensions - dimensions of box representation of component in meters.
capabilities
cost - optional currency and value.
file3D - name of .stl file for 3D visualization. If not provided, a cuboid is used.
id - string corresponding base object id on the ship specification. Same as the property's name (for this case, baseObject).
weightInformation - contains several properties for calculating mass and center of gravity of the object. For a tank, then CG will typically be defined by a fullnessCGMapping, which maps automatically to a CG for a given tank fullness state. This will typically also be accompanied by the properties contentDensity (in kg/m³) and volumeCapacity (in m³), for calculating the mass of the content. Alternatively, CG can be defined as a fixed position (relative to the center of the base of the specified box).

A BaseObject can be constructed as:

let baseObject = new Vessel.BaseObject(specification);

Methods:

baseObject.getSpecification() <> - returns an object with all specification data pertaining to this base object.
baseObject.getWeight(fullness) <> - returns component weight based on its fullness state.
baseObject.setFromSpecification(spec) <> - fills the base object with data from the specification.

DerivedObject

A derived object is a base object with information added on top of it. The specification is defined as:

derivedObjSpec:  {
    "id": "Tank1",
    "baseObject": "baseTank",   
    "referenceState": {
        "xCentre": 16.875,
        "yCentre": 0,
        "zBase": 0.4
    },
    "affiliations": {
        "group": "cargo tanks",
        ...
    }
};

Properties:

affiliations - includes name of the deck where the component is physically located and the component's corresponding SFI code.
baseObject - identification tag of the base object.
id - identification tag of the derived object.
referenceState - default location of 3D component inside the ship in meters.

A DerivedObject can be constructed as:

let derivedObject = new Vessel.DerivedObject(specification, baseObjects);

Methods:

derivedObject.getSpecification() <> - returns an object with all specification data pertaining to this derived object.
derivedObject.getWeight(state) <> - returns component weight based on its state.
derivedObject.setFromSpecification(spec) <> - fills the derived object with data from the specification.
derivedObject.baseObject <> - points to the original base object used to obtain the derived object.
derivedObject.baseObjects <> - points to the entire specification database from which the base object comes from.

Hull

This class represents the ship hull, with properties for calculating weight and water line shape. It also includes properties for GM calculation and for truncating hull visualization according to draft. When having a class for this, the specification can possibly be in one of several formats, and the handling will be contained in this class.

When having a class for this, the specification can possibly be in one of several formats, and the handling will be contained in this class. There is reduced dependency on the ship object, in order to be able to optimize updates. An example of hull specification is:

"hull": {
	"attributes": {
		"LOA": 22.5,
		"BOA": 10,
		"Depth": 2.5,
		"APP": 0
	},
	"halfBreadths": {
		"waterlines": [0, 0, 1],
		"stations": [0, 1],
		"table": [[0, 0], [1, 1], [1, 1]]
	},
	"buttockHeights": {}
}

Where:

attributes - collects hull main dimensions in meters.
halfBreadths - hull offset table data, as fractions of the main dimensions.

A Hull object can be constructed as:

let hull = new Vessel.Hull(spec);

Methods:

hull.calculateAttributesAtDraft() <> - returns an object with hull geometric coefficients at the current draft.
hull.calculateDraftAtMass(M, epsilon=0.001, rho=1025) <> - returns draft corresponding to a given displacement M, with epsilon being the tolerance interval for estimation of the draft.
hull.getSpecification() <> - returns an object with all specification data pertaining to this hull object.
hull.getStation(x) <> - returns the station data related to the given input x.
hull.getWaterline(z, nanCorrectionMode=1) <> - returns the waterline data related to the given input. z: level from bottom of ship (absolute value in meters). nanCorrectionMode: 0 to set all NaNs to zero, 1 to output NaNs, set all NaNs to zero, 2 to replace NaNs with interpolated or extrapolated values.
hull.getWeight(designState) <> - returns estimate of hull weight. The estimation method is based on Watson and Gilfillan modeling approach using a specific modification of the Lloyd's Equipment Numeral E as the independent variable.
hull.setFromSpecification(spec) <> - fills the hull object with data from the specification.
hull.stationCalculation(x) <> - calculates geometric coefficients for a given hull station.
hull.waterlineCalculation(z, bounds) <> - calculates geometric coefficients for a given hull waterline.
hull.levels <> - hull geometric properties calculated for predefined waterline level.
hull.levelsNeedUpdate <> - flag for indicating necessity to recalculate geometric properties of the hull. Set to true if the geometry (stations, waterlines or offsets table) or main dimensions are modified, in order to redo the cached calculations.

ShipState

A ShipState object holds several parameters that affect calculations. It is constructed as:

let shipState = new Vessel.ShipState(spec);

A Ship object is required to have a designState, which is an instance of ShipState. Some calculations, like ship.getWeight, can be done with an external shipState parameter, e.g. to test different load configurations on the same ship without modifying the ship specification. The ShipState object now mainly accounts for load state, or states of derivedObjects in the ship.

The object state assignments also have a baseByGroup. A group of baseObjects could for instance be a category including all tanks that carry a given compound, regardless of their size and shape. The same goes for derivedByGroup. With this, there would be five types of assignments:

common: All objects.
baseByGroup: Applies to every object that has its base object's property group set to the given name.
baseByID: Applies to all objects that have base object consistent with the given ID.
derivedByGroup: Applies to every object that has its property group set to the given name.
derivedByID: Applies only to the object with given ID.

Where assignments of subsequent types override assignments of previous types. The caching and version control of ship states is incomplete at this stage.

Methods:

shipState.extend(spec) <> - overrides existing directives and adds new ones.
shipState.getObjectState(o) <> - returns object o state.
shipState.getObjectStateProperty(o, k) <> - o is an object, k is a key to a single state property.
shipState.getSpecification() <> - returns an object with all specification data pertaining to this ship state object.
shipState.override(spec) <> - only appllies directives of spec that have a corresponding directive in this.
shipState.setFromSpecification(spec) <> - fills the ship state object with data from the specification.

Properties:

shipState.calculationParameters
shipState.objectCache
shipState.objectOverrides
shipState.version <> - version counter for ship state updates. This must be incremented manually whenever changes are made to the state, in order for new state-dependent calculations to be made. This is because the ShipState class uses calculation caching internally.

calculationParameters

An arbitrary collection of specified ship parameters which can be used for calculations. The practice of having some calculation parameters in the ShipState will have to be refined in the future. Some parameters, such as LWL and Cb, can be calculated from load and hull geometry. Other parameters are uncertain, or otherwise not covered by the existing calculations. Having them in the ShipState can be useful.

shipState.calculationParameters.Cb_design <> - block coefficient.
shipState.calculationParameters.Co <> -
shipState.calculationParameters.Draft_design <> - design draft.
shipState.calculationParameters.K <> -
shipState.calculationParameters.LWL_design <> - waterline length.
shipState.calculationParameters.MCR <> - engine's maximum continuous rating.
shipState.calculationParameters.SFC <> - engine's specific fuel consumption (constant).
shipState.calculationParameters.crew <> - number of crew.
shipState.calculationParameters.speed <> - design speed.
shipState.calculationParameters.tripDuration <> - duration of a typical trip.

objectCache

shipState.derivedObject.state <> - includes current state's filling and position info.
shipState.derivedObject.thisStateVer <> - flag for indicating state version.

objectOverrides

Those define how the object states are assigned. There are currently four types of state assignments, each related to one of the properties below. Assignments of subsequent types override assignments of previous types.

shipState.objectOverrides.baseByID <> - applies to all objects that have base object consistent with the given ID.
shipState.objectOverrides.common <> - all objects.
shipState.objectOverrides.deviredByGroup <> - applies to every object that has its property "group" set to the given name.
shipState.objectOverrides.derivedByID <> - applies only to the object with given ID.

Structure

Defines structure characteristics: hull, decks and bulkheads. A Structure specification contains the following objects:

structure.bulkheads
structure.decks
structure.hull (a Hull object instance)

A Structure object can be constructed as:

let structure = new Vessel.Structure(spec);

Methods:

structure.getSpecification() <> - returns an object with all specification data pertaining to this structure object.
structure.getWeight(designState) <> - returns structure weight based on its state.
structure.setFromSpecification(spec) <> - fills the structure object with data from the specification.

bulkheads

Definition:

"bulkhead1": {
	"xAft": 50,
	"thickness": 0.1,
	"density": 7850
}

Where:

xAft - longitudinal position of the bulkhead in meters.
thickness - thickness of the bulkhead in meters.
density - density of the bulkhead's steel in kg/m³.

decks

Definition:

"deck1": {
	"zFloor": 13.8,
	"thickness": 0.08,
	"xAft": 44,
	"xFwd": 82,
	"yCentre": 0,
	"breadth": 18,
	"density": 7850
}

Where:

zFloor - z position of the deck (height) in meters.
thickness - thickness of the deck in meters.
xAft - maximum aft reach of the deck in meters.
xFwd - maximum forward reach of the deck in meters.
yCentre - center of the deck in y direction in meters.
breadth - deck's breadth in meters.
density - density of the deck's steel in kg/m³.

browseShip

Vessel.browseShip() <> - handy function for letting the user load a ship design from a local file. Depends on Ship and the other core classes. Typical usage:

<a onclick="browseShip(useShip)">Click here</a>

Where useShip takes the loaded ship design as a parameter and does something with it. According to the ECMAScript standard, it is required that the file browsing is initiated by the user. Google Chrome seems to handle indirect initiation very well, such as having this function in a click handler.

downloadShip

Vessel.downloadShip(ship) <> - very simple download of the specification of a given ship design. Depends on a working getSpecification method.

loadShip

Vessel.loadShip(url, callback) <> - handy function for loading a ship design from file. Depends on Ship and the other core classes. Typical usage:

var myShip;
var filePath = "ships/myShip.json";
Vessel.loadShip(filePath, function(ship) {
	myShip = ship;
	doSomething();
});

Ship Design and Operation Lab, NTNU in Ålesund.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API Reference

Table of Contents

Ship

BaseObject

DerivedObject

Hull

ShipState

calculationParameters

objectCache

objectOverrides

Structure

bulkheads

decks

browseShip

downloadShip

loadShip

Vessel.js

Clone this wiki locally