# 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)

Column | Type | Description |
---|---|---|

ID (id) | integer | Unique identifier of the row in the table. |

Number (number) | integer | Permanent number of the asteroid assigned by the Minor Planet Center. |

Name (name) | string | Permanent name of the asteroid assigned by the Minor Planet Center. |

Designation (designation) | string | Provisional designation of the asteroid. |

Comment (comment) | string | Additional free-text information. |

Created (created) | datetime | Timestamp of the creation of the record. |

Modified (modified) | datetime | Timestamp of the last modification of the record. |

### Models (asteroid_models)

Column | Symbol | Type | Description |
---|---|---|---|

ID (id) | integer | Unique identifier of the row in the table. | |

Asteroid ID (asteroid_id) | integer | Foreign key: The ID of the asteroid to which this model belongs. | |

Lambda (lambda) | λ | float | Ecliptic longitude of the spin axis (J2000.0, degrees). |

Beta (beta) | β | float | Ecliptic latitude of the spin axis (J2000.0, degrees). |

Period (period) | P | float | Sidereal rotation period (hours). |

YORP (yorp) | float | Linear change in the rotation rate dω/dt caused by the Yarkovsky-O'Keefe-Radzievskii-Paddack effect (rad/day^{2}). | |

JD0 (jd0) | t_{0} | float | Initial time (Julian date epoch). |

Phi0 (phi0) | φ_{0} | float | Initial rotation angle for t_{0} (degrees). |

Light Scattering Model (lsm) | string | Used light-scattering model (LSM): LSL = Lambert + Lommel-Seeliger; H = Hapke. | |

LSM Parameter 1 (lsm_p1) | p_{1} | float | Lambertian part of LSL. | Single-particle scattering albedo w for H. |

LSM Parameter 2 (lsm_p2) | p_{2} | float | Amplitude a of the phase angle function for LSL. | Asymmetry parameter of the single-particle phase function g for H. |

LSM Parameter 3 (lsm_p3) | p_{3} | float | Width d of the phase angle function for LSL. | Opposition surge amplitude B_{0} for H. |

LSM Parameter 4 (lsm_p4) | p_{4} | float | Slope k of the phase angle function for LSL. | Opposition surge width h for H. |

LSM Parameter 5 (lsm_p5) | p_{5} | float | Not used for LSL. | Macroscopic roughness θ_{0} for H. |

Calibrated Size (calibrated_size) | boolean | 1 (Yes) = the model is scaled to its real size (in km), 0 (No) = the model is scaled to unit volume. | |

Equivalent Diameter (equiv_diameter) | D | float | Diameter of a sphere that has the same volume as the model (km). |

Equivalent Diameter Error (equiv_diameter_err) | σ_{D} | float | Estimated error of the equivalent diameter (km). |

Thermal Inertia (thermal_inertia) | Γ | float | Thermal inertia (J m^{−2} s^{1/2} K^{−1}). |

Thermal Inertia Min (thermal_inertia_min) | Γ_{min} | float | Lower limit for Γ – estimation of the uncertainty interval. |

Thermal Inertia Max (thermal_inertia_max) | Γ_{max} | float | Upper limit for Γ – estimation of the uncertainty interval. |

Visual Albedo (visual_albedo) | p_{V} | float | Visual geometric albedo. |

Visual Albedo Error (visual_albedo_err) | σ_{pV} | float | Error of the visual geometric albedo. |

Craters Angle (craters_angle) | γ_{c} | float | Opening angle of craters (deg) – for describing the surface roughness. |

Craters Surface Density (craters_surface_density) | ϱ_{c} | float | Areal density of craters – for describing the sufrace roughness. |

Quality Flag (quality_flag) | float | Reliability of the model; 0 for lowest, 5 for highest. | |

Nonconvex (nonconvex) | boolean | 1 (Yes) = the model is nonconvex; 0 (No) = the model is convex. | |

Version (version) | string | Model version, usually in the form of a date YYYY-MM-DD. | |

Comment (comment) | string | Additional free-text information. | |

Created (created) | datetime | Timestamp of the creation of the record. | |

Modified (modified) | datetime | Timestamp of the last modification of the record. |

##### Quality flag

*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.)

Column | Symbol | Type | Description |
---|---|---|---|

ID (id) | integer | Unique identifier of the row in the table. | |

Asteroid ID (asteroid_id) | integer | Foreign key: The ID of the asteroid to which this model belongs. | |

Lambda Angular Momentum (lambda_angular_momentum) | λ_{L} | float | Ecliptic longitude of the angular momentum vector (J2000.0, degrees). |

Beta Angular Momentum (beta_angular_momentum) | β_{L} | float | Ecliptic latitude of the angular momentum vector (J2000.0, degrees). |

Period Phi (period_phi) | P_{φ} | float | Precession period (hours). |

Period Psi (period_psi) | P_{ψ} | float | Rotation period (hours). |

JD0 (jd0) | t_{0} | float | Initial time (Julian date epoch). |

Phi0 (phi0) | φ_{0} | float | Initial precession angle for t_{0} (degrees). |

Psi0 (psi0) | ψ_{0} | float | Initial rotation angle for t_{0} (degrees). |

Theta0 (theta0) | θ_{0} | float | Initial nutation (tilt) angle for t_{0} (degrees). |

Moment of Inertia 1 (moment_of_inertia_1) | I_{1} | float | First component of the moment of inertia vector (I_{3} = 1). |

Moment of Inertia 2 (moment_of_inertia_2) | I_{2} | float | Second component of the moment of inertia vector (I_{3} = 1). |

Angular Momentum (angular_momentum) | L | float | Size of the angular momentum vector. |

Light Scattering Model (lsm) | string | Used light-scattering model (LSM): LSL = Lambert + Lommel-Seeliger; H = Hapke. | |

LSM Parameter 1 (lsm_p1) | p_{1} | float | Lambertian part of LSL. | Single-particle scattering albedo w for H. |

LSM Parameter 2 (lsm_p2) | p_{2} | float | Amplitude a of the phase angle function for LSL. | Asymmetry parameter of the single-particle phase function g for H. |

LSM Parameter 3 (lsm_p3) | p_{3} | float | Width d of the phase angle function for LSL. | Opposition surge amplitude B_{0} for H. |

LSM Parameter 4 (lsm_p4) | p_{4} | float | Slope k of the phase angle function for LSL. | Opposition surge width h for H. |

LSM Parameter 5 (lsm_p5) | p_{5} | float | Not used for LSL. | Macroscopic roughness θ_{0} for H. |

Calibrated Size (calibrated_size) | boolean | 1 (Yes) = the model is scaled to its real size (in km), 0 (No) = the model is scaled to unit volume. | |

Equivalent Diameter (equiv_diameter) | D | float | Diameter of a sphere that has the same volume as the model (km). |

Equivalent Diameter Error (equiv_diameter_err) | σ_{D} | float | Estimated error of the equivalent diameter (km). |

Nonconvex (nonconvex) | boolean | 1 (Yes) = the model is nonconvex; 0 (No) = the model is convex. | |

Version (version) | string | Model version, usually in the form of a date YYYY-MM-DD. | |

Comment (comment) | string | Additional free-text information. | |

Created (created) | datetime | Timestamp of the creation of the record. | |

Modified (modified) | datetime | Timestamp of the last modification of the record. |

### References (references)

Column | Type | Description |
---|---|---|

ID (id) | integer | Unique identifier of the row in the table. |

Bibcode (bibcode) | string | Astronomical identifier of this reference; format: YYYYJJJJJVVVVMPPPPA, e.g. "2010A&A...513A..46D". See Bibcode on Wikipedia. |

Author (author) | text | List of authors separated by semicolons, e.g. "Ďurech, J.; Sidorin, V.; Kaasalainen, M.". |

Author Short (author_short) | string | Author(s) in a short form, used when citing in text, e.g. "Ďurech et al.". |

Year (year) | integer | Year of publication. |

Title (title) | text | Title. |

Journal (journal) | string | Journal. |

Volume (volume) | string | Journal volume. |

Page (page) | string | Journal page. |

Url (url) | text | Link to the source. |

Comment (comment) | string | Additional free-text information. |

Created (created) | datetime | Timestamp of the creation of the record. |

Modified (modified) | datetime | Timestamp 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.

Example: Asteroid (2) Pallas – Model [101]