# Documentation

## DAMIT asteroid models

DAMIT contains asteroid models that were derived using the light-curve inversion method developed by Kaasalainen & Torppa (2001) and Kaasalainen et al. (2001), combined with other inversion techniques in some cases. Each model in DAMIT references the original paper(s) where it was published. Please note that the models presented in DAMIT may differ from those published in the original papers. The main reason for this is a limited dataset used in the original publication and/or a narrow range of periods scanned during the inversion.

DAMIT models are stored in a relational database (currently MySQL) and associated data files. The database tables and types of standard files are described below.

### Naming conventions

#### Models vs Tumblers

Apart from "standard" asteroid models, referred to as simply Models, DAMIT also contains models that are in excited rotational states. These "excited" models are referred to as Tumblers. Their rotation can be described as free precession (see Kaasalainen, 2001). As Models and Tumblers use different sets of parameters, they are stored in two separate tables: asteroid_models and tumblers.

## Basic tables

Identifiers of tables and columns used in the database schema are given in parentheses.

### Asteroids (asteroids)

ColumnTypeDescription
ID (id)integerUnique identifier of the row in the table.
Number (number)integerPermanent number of the asteroid assigned by the Minor Planet Center.
Name (name)stringPermanent name of the asteroid assigned by the Minor Planet Center.
Designation (designation)stringProvisional designation of the asteroid.
Created (created)datetimeTimestamp of the creation of the record.
Modified (modified)datetimeTimestamp of the last modification of the record.

### Models (asteroid_models)

ColumnSymbolTypeDescription
ID (id)integerUnique identifier of the row in the table.
Asteroid ID (asteroid_id)integerForeign key: The ID of the asteroid to which this model belongs.
Lambda (lambda)λfloatEcliptic longitude of the spin axis (J2000.0, degrees).
Beta (beta)βfloatEcliptic latitude of the spin axis (J2000.0, degrees).
Period (period)P floatSidereal rotation period (hours).
JD0 (jd0)t0floatInitial time (Julian date epoch).
Phi0 (phi0)φ0floatInitial rotation angle for t0 (degrees).
Light Scattering Model (lsm)stringUsed light-scattering model (LSM): LSL = Lambert + Lommel-Seeliger; H = Hapke.
LSM Parameter 1 (lsm_p1)p1floatLambertian part of LSL. | Single-particle scattering albedo w for H.
LSM Parameter 2 (lsm_p2)p2floatAmplitude a of the phase angle function for LSL. | Asymmetry parameter of the single-particle phase function g for H.
LSM Parameter 3 (lsm_p3)p3floatWidth d of the phase angle function for LSL. | Opposition surge amplitude B0 for H.
LSM Parameter 4 (lsm_p4)p4floatSlope k of the phase angle function for LSL. | Opposition surge width h for H.
LSM Parameter 5 (lsm_p5)p5floatNot used for LSL. | Macroscopic roughness θ0 for H.
Calibrated Size (calibrated_size)boolean1 (Yes) = the model is scaled to its real size (in km), 0 (No) = the model is scaled to unit volume.
Equivalent Diameter (equiv_diameter)DfloatDiameter of a sphere that has the same volume as the model (km).
Equivalent Diameter Error (equiv_diameter_err)σDfloatEstimated error of the equivalent diameter (km).
Thermal Inertia (thermal_inertia)ΓfloatThermal inertia (J m−2 s1/2 K−1).
Thermal Inertia Min (thermal_inertia_min)ΓminfloatLower limit for Γ – estimation of the uncertainty interval.
Thermal Inertia Max (thermal_inertia_max)ΓmaxfloatUpper limit for Γ – estimation of the uncertainty interval.
Visual Albedo (visual_albedo)pVfloatVisual geometric albedo.
Visual Albedo Error (visual_albedo_err)σpVfloatError of the visual geometric albedo.
Craters Angle (craters_angle)γcfloatOpening angle of craters (deg) – for describing the surface roughness.
Craters Surface Density (craters_surface_density)ϱcfloatAreal density of craters – for describing the sufrace roughness.
Quality Flag (quality_flag)floatReliability of the model; 0 for lowest, 5 for highest.
Nonconvex (nonconvex)boolean1 (Yes) = the model is nonconvex; 0 (No) = the model is convex.
Version (version)stringModel version, usually in the form of a date YYYY-MM-DD.
Created (created)datetimeTimestamp of the creation of the record.
Modified (modified)datetimeTimestamp of the last modification of the record.
##### Quality flag
Each shape model comes with its uncertainty that depends on the amount, variety, and quality of the data used for the model determination, and should be taken into account in further shape model applications. To provide some information about the reliability of the derived shape model, we introduce the Quality Flag value that is a number between 0 and 5 assigned to each shape model solution. It can be a non-integral number, e.g. 3.5. The scale is as follows:
• 5 – "Ground-truth" models reconstructed from images obtained by spacecraft (usually not included in DAMIT but available through PDS).
• 4 – Models based on a large photometric data set and disk-resolved data and/or stellar occultations, the pole ambiguity is resolved, they should well correspond to the real shape of the asteroid.
• 3 – Reliable models based on large photometric data sets.
• 2 – Models reconstructed from only few dense light curves combined with sparse data, the shape is not very certain.
• 1 – Coarse shape models based solely on sparse data, large errors both in the shape and pole direction.
• 0 – Just one possible model out of many.

### Tumblers (tumblers)

(Tumblers are models that are in excited rotational states.)

ColumnSymbolTypeDescription
ID (id)integerUnique identifier of the row in the table.
Asteroid ID (asteroid_id)integerForeign key: The ID of the asteroid to which this model belongs.
Lambda Angular Momentum (lambda_angular_momentum)λLfloatEcliptic longitude of the angular momentum vector (J2000.0, degrees).
Beta Angular Momentum (beta_angular_momentum)βLfloatEcliptic latitude of the angular momentum vector (J2000.0, degrees).
Period Phi (period_phi)PφfloatPrecession period (hours).
Period Psi (period_psi)PψfloatRotation period (hours).
JD0 (jd0)t0floatInitial time (Julian date epoch).
Phi0 (phi0)φ0floatInitial precession angle for t0 (degrees).
Psi0 (psi0)ψ0floatInitial rotation angle for t0 (degrees).
Theta0 (theta0)θ0floatInitial nutation (tilt) angle for t0 (degrees).
Moment of Inertia 1 (moment_of_inertia_1)I1floatFirst component of the moment of inertia vector (I3 = 1).
Moment of Inertia 2 (moment_of_inertia_2)I2floatSecond component of the moment of inertia vector (I3 = 1).
Angular Momentum (angular_momentum)LfloatSize of the angular momentum vector.
Light Scattering Model (lsm)stringUsed light-scattering model (LSM): LSL = Lambert + Lommel-Seeliger; H = Hapke.
LSM Parameter 1 (lsm_p1)p1floatLambertian part of LSL. | Single-particle scattering albedo w for H.
LSM Parameter 2 (lsm_p2)p2floatAmplitude a of the phase angle function for LSL. | Asymmetry parameter of the single-particle phase function g for H.
LSM Parameter 3 (lsm_p3)p3floatWidth d of the phase angle function for LSL. | Opposition surge amplitude B0 for H.
LSM Parameter 4 (lsm_p4)p4floatSlope k of the phase angle function for LSL. | Opposition surge width h for H.
LSM Parameter 5 (lsm_p5)p5floatNot used for LSL. | Macroscopic roughness θ0 for H.
Calibrated Size (calibrated_size)boolean1 (Yes) = the model is scaled to its real size (in km), 0 (No) = the model is scaled to unit volume.
Equivalent Diameter (equiv_diameter)DfloatDiameter of a sphere that has the same volume as the model (km).
Equivalent Diameter Error (equiv_diameter_err)σDfloatEstimated error of the equivalent diameter (km).
Nonconvex (nonconvex)boolean1 (Yes) = the model is nonconvex; 0 (No) = the model is convex.
Version (version)stringModel version, usually in the form of a date YYYY-MM-DD.
Created (created)datetimeTimestamp of the creation of the record.
Modified (modified)datetimeTimestamp of the last modification of the record.

### References (references)

ColumnTypeDescription
ID (id)integerUnique identifier of the row in the table.
Bibcode (bibcode)stringAstronomical identifier of this reference; format: YYYYJJJJJVVVVMPPPPA, e.g. "2010A&A...513A..46D". See Bibcode on Wikipedia.
Author (author)textList of authors separated by semicolons, e.g. "Ďurech, J.; Sidorin, V.; Kaasalainen, M.".
Author Short (author_short)stringAuthor(s) in a short form, used when citing in text, e.g. "Ďurech et al.".
Year (year)integerYear of publication.
Title (title)textTitle.
Journal (journal)stringJournal.
Volume (volume)stringJournal volume.
Page (page)stringJournal page.
Created (created)datetimeTimestamp of the creation of the record.
Modified (modified)datetimeTimestamp of the last modification of the record.

## Association tables

Association tables link rows from the basic tables to resolve many-to-many relations. These tables link, for example, models and references, as one model can be linked to many different references, and one reference can be linked to many different models. (Read more about association tables and many-to-many relations on Wikipedia.)

### Models – References (asteroid_models_references)

Column Type Description
id integer Unique identifier of the row in the table.
asteroid_model_id integer Foreign key: The ID of the linked model.
reference_id integer Foreign key: The ID of the linked reference.

### Tumblers – References (references_tumblers)

Column Type Description
id integer Unique identifier of the row in the table.
tumbler_id integer Foreign key: The ID of the linked tumbler.
reference_id integer Foreign key: The ID of the linked reference.

## Standard files

### Spin (spin.txt)

Basic parameters describing a model can be obtained in the form of Spin (spin.txt) files. The format is as follows: The first line contains $\lambda$ (degrees), $\beta$ (degrees), and $P$ (hours), separated with spaces. The second line contains $t_0$ (JD epoch) and $\varphi_0$ (degrees). The third line, if present, contains the parameters of the light-scattering model, $p_1$ to $p_5$.

### Model shape (shape.txt)

Asteroid models are represented as polyhedrons with triangular surface facets. The format of shape files is as follows: The first line gives the number of vertices and facets, then follow the vertex $x$, $y$, $z$ coordinates (defining radius vectors $r_\up{ast}$), then for each facet the order numbers of facet vertices (anticlockwise seen from outside the body). The orientation of a model at epoch $t$ is given by a transformation between vectors $r_\up{ast}$ in the asteroid co-rotating coordinate frame and vectors $r_\up{ecl}$ in the ecliptic coordinate frame. The transformation is given by the equation $$r_\text{ecl} = \up{R}_z(\lambda) \; \up{R}_y(90\degree - \beta) \; \up{R}_z\left( \varphi_0 + \frac{2\pi}{P}(t - t_0) \right) \; r_\up{ast} ,$$ where $\up{R}_i(\theta)$ is the rotation matrix corresponding to the rotation of a vector through the angle $\theta$ along the $i$-axis in the anticlockwise direction. Namely $${ \up{R}_z(\theta) = \begin{pmatrix} \cos\theta & -\sin\theta & 0 \\ \sin\theta & \cos\theta & 0 \\ 0 & 0 & 1 \\ \end{pmatrix} },\;\; { \up{R}_y(\theta) = \begin{pmatrix} \cos\theta & 0 & \sin\theta \\ 0 & 1 & 0 \\ - \sin\theta & 0 & \cos\theta \\ \end{pmatrix} },\;\;$$ $\lambda$ and $\beta$ are ecliptic longitude and latitude of the spin axis respectively, $P$ is the rotation period, $\varphi_0$ is the initial rotation angle, and $t_0$ is the initial epoch. In some cases, the nonzero linear change of the rotation rate $\upsilon$ caused by the YORP effect must be taken into account. The corresponding rotation matrix is then $$\up{R}_z\left( \varphi_0 + \frac{2\pi}{P}(t - t_0) + \frac{1}{2}\upsilon(t - t_0)^2 \right).$$

### Light curves (lc.txt, lc.json, lc.ref.txt)

The models are based on light-curve data that can be exported to plaintext files (lc.txt). These files have the following format: The first line gives the total number of light curves, then individual light curves follow in blocks. Each light curve starts with a header line that gives the number of points followed by 0/1 code for a relative (0) or calibrated (1) light curve. Then follow lines with the light-time corrected JD epoch, the brightness in intensity units (reduced to a unit distance from Earth and the Sun when calibrated), the ecliptic asteroid-centric cartesian coordinates $x$, $y$, $z$ of the Sun and of the Earth in AU.

Alternatively, light curves can be exported to structured JSON text files (lc.json). These files contain both data points and metadata, e.g. light curve ID, scale, or related references. JSON files are suitable for further programmatic processing.

lc.ref.txt files: These files contain a list of all light curves belonging to a given asteroid, for example: A103.lc.ref.txt. The first column gives the light curve serial number (this is not the unique light curve ID in the database); the second column gives the mean observation date or the range of dates for sparse light curves; the remainder of the line gives the references.

### Pregenerated images of models (shape.png, 3D.pdf)

Each model is shown from three directions in the corresponding PNG file. There are two views from asteroid's equator and one from its pole. The three views correspond to the views from the positive $x$, $y$, $z$ axes, respectively. The light-scattering model used for rendering has no physical meaning and was chosen just for visualization purposes. Some models also provide an interactive 3D animation in the PDF format that works with Acrobat Reader 8 or higher.

### Spin parameters according to the IAU recommendation (IAUspin.txt)

The IAUspin file gives the parameters of the rotation state according to the recommendations of the IAU (Seidelmann et al. 2007): $\alpha_0$, $\delta_0$, $\d W/\d t$ (the first line), and $t_0$, $W_0$ (the second line). Here $\alpha_0$ and $\delta_0$ are equatorial coordinates of the pole (degrees), $\d W/\d t$ is the rotation rate (deg/day), and $t_0$ is the initial epoch for which the position of the prime meridian is $W_0$ (degrees). The position of the prime meridian at the time $t$ is $W = W_0 + \d W/\d t (t - t_0)$. The prime meridian is defined by the positive $x$ axis.

### Occultations (OCC*.pdf)

Some models in the database were scaled to fit the occultation data. For these asteroids, the sky-plane projection of the model was computed for the time of occultation and plotted together with the occultation chords. The meaning of different types of lines and curves is explained in the schematic occ_explanation.pdf (PDF 9.8 KiB). For more details see Ďurech et al. (2011) (preprint PDF 468 KiB).

### Wavefront .obj file (shape.obj)

Models are also provided in the OBJ format that is recognized by most 3D graphics applications. OBJ files are generated from shape files (shape.txt). More about the OBJ file format can be found at Wikipedia.

## Sky projection

Besides pregenerated PNG and 3D files, we also developed a JavaScript application for on-line models visualisation. It is available in the detailed view of a model and allows you to generate its sky projection for an arbitrary time (Julian Date). The projection shows two pictures. The first picture represents a given model illuminated by the Sun only, the second picture represents the model under artificial illumination to show its outline in the sky. Both pictures show the model as viewed from Earth at a given Julian Date; the north is up and west is right. The projection also takes into account the light-time effect; i.e. the model's orientation is calculated for the retarded time $t_\up{ret} = t − \Delta/c$, where $t$ is the observation time, $\Delta$ is the distance between the asteroid and Earth, and $c$ is the speed of light.

Please note that the model visualisation is available for "standard" models only, not for tumblers.