| |
| Diamond
calculator : Documentation |
 |
| |
|
Appraiser file format |
|
This documents shows technical description of Appraise.txt
file format. Appraise.txt file is located in the
folder where DiamCalc is installed. This file defines criteria by which DiamCalc
grades diamonds (i.e. defines quality of diamonds' parameters) depending on a
selected grading system ("appraiser"). A technical description of Appraise.txt
file format is given below. To
understand how the data can be modified to change grading criteria, see
<How to modify appraiser data>. For
a less technical information, see <How
DiamCalc grades diamonds> for a common-language description of appraising
process, and for human-readable tables that corresponds to DiamCalc grading methods.
See
<Appraising diamonds quality and pricing diamonds>
for relation between appraising diamonds and calculating their price, as it is
done by DiamCalc, and for related links. 1.General
structure of Appraise.txt file 2.Comments
(";"), spaces and split lines | | |
| | | |
| |
1.
General structure of Appraise.txt file |
|
The structure
of the file is defined by sections, each one begins with a keyword in brackets
(e.g. "[Appraiser]", "[quality]",
"[cut]", etc.) and ends with an
"[end]" line. On the top level,
the file consists of several "[Appraiser]"
- "[end]" blocks, each for one
appraiser. Inside those blocks, there are some other blocks ("[quality]"
- "[end]", etc.). The blocks are
indented by spaces to make their scope more understandable. The
general structure looks like the following: ;
AGA appraiser [Appraiser]
...
[quality]
...
[end]
[other]
...
[end]
[cut]
...
[end]
[end]
; GIA appraiser
...
("..." means that some lines were skipped). First, select
an appraiser which data you would like to examine or modify by browsing the file
for appropriate "[Appraiser]" -
"[end]" section. Then look at that
part of file for specific appraiser data (see other sections of this manual for
details). Top
of this page | | |
| | | |
| |
2.
Comments (";"), spaces and split lines
|
Each line that begins with ";"
symbol (semicolon) is a comment. Such lines are ignored by the software, but they
can provide valuable description of the data to a human who reads the file. You
can safely remove any comments from the file, or add your own by putting text
on a separate line and beginning it with ";".
The software ignores white space between lines and extra white space between words,
e.g. if a sequence "1A 0" occurs anywhere in the file, it can be substituted
by "1A 0" with no change in meaning. Tab symbols are ignored also. The
format allows to split long lines (splitting should not break words, i.e. it should
occur at a white space only). When a line is split, the beginning is placed at
a separate line and "\" symbol (backslash) is added at the end after a space.
The end of line should be placed on the next line of file without any modifications.
It is recommended to keep existing formatting,
as it was chosen to make the file more readable. For example, it is easy to find
a pair "[end]" line for a "[cut]"
line, as there are equal number of spaces before each of those lines. Top
of this page | | |
| | | |
| |
3.
Structure of appraiser data | [Appraiser]
- [End] block |
An "[Appraiser]"
- "[end]" block holds the data
of one appraiser. You can identify if some "[Appraiser]"
tag corresponds to the grading system you need in one of two ways: a)
Looking for a comment just before the "[Appraiser]"
tag. It can be, for instance, ";
GIA" line for GIA grading system. b) Looking
for "Title: ..." line couple of lines below of the "[Appraiser]"
tag. For instance, it is "Title: GIA" for GIA appraiser. Besides
"Title:", there can be other lines
at the beginning of the appraiser data, like "Version: ..." and "Serial
Number: ...". It is an internal file information, leave it as is. Some
blocks may follow in the appraiser description, such as "[quality]"
- "[end]" block (it lists quality
groups used by this appraiser), "[other]"
- "[end]" block (it contains, for
example, information on what "Thick" girdle is in numerical terms), and a "[cut]"
- "[end]" block (may be several
of them; each one defines quality groups for one or several cut types).
Content of each section is indented by spaces, so
it is easy to find the beginning and the end of each sections and see if one of
them is inside another one. Top
of this page | | |
| | | |
| |
4.
Structure of quality groups list |
[Quality] - [End] block |
A
"[quality]" - "[end]"
block lists quality groups used by that appraiser, discounts for those groups,
and maybe some additional information. Each quality group listed on a separate
line inside the "[quality]" - "[end]"
block. For example, let us look at list of HRD grades (it is located in HRD appraiser
data): [quality]
Excellent
0 "Very
good" 0 Good
10 Fair
15 [end]
It means that there are four quality groups. Each
line begins with the name for a quality group, the following number is the discount
in percents. Note that if the name consists of two words or more, it should be
surrounded by quotes ("Very good" in the example above). Some
additional information may follow the discount, for instance, as in AGA appraiser
data: 2A
10 RGB 200 200 200 In
this case, 2A is the name of the quality group, 10 means the discount for quality
(in percents). The rest should be left as is (it defines the color by which this
quality group will be displayed). Top
of this page | | |
| | | |
| |
5.
Structure of translation |
[Other] - [End] block |
An "[other]"
- "[end]" block defines translation
tables for parameters values, that is a relation between a parameter's numeric
and verbal values (for example, a "Large" culet in AGA appraiser is defined as
0.22 to 0.4 millimeters wide). There are typically
several "long" lines inside "[other]"
- "[end]" sections. (Remember:
"\" (backslash) symbol at the end of a line means that the following line is a
continuation of this one. So if you see several consecutive lines in the file
that end with "\" except the last one, the software will treat those lines as
a single one, ending backslashes are ignored. We can call such line a "long" one.)
The "long" lines in "[other]"
- "[end]" blocks can begin with
the following: | DefaultParameter:
... | - currently not used,
but leave such lines as is | | StringValue:
GirdleHeight_GIA (%) ... | -
defines values of girdle thickness | | StringValue:
Culet_mm (.) ... | - lists
values of culet size | "StringValue:..."
strings have the following format: after a parameter's name, list of possible
values along with two numerical values (minimum and maximum numerical values)
follows. For example, the beginning of girdle thickness values list in AGA system
looks like the following: StringValue:
GirdleHeight_GIA (%) \
"Ext. thin" 0. 0.4 \
"Very thin" 0.4 1.0 \ Thin
1.0 1.5 \ ...
It should be read this way: the translation
table describes girdle thickness (note that "_GIA" suffix in the parameter
name does not mean that GIA parameter values are assumed, only that the girdle
thickness is measured the way which is used in GIA system). "(%)" means that the
value is measured in percents of diameter. Extremely thin ("Ext. thin")
girdle is defined as having a width between 0 and 0.4 % of diameter, "Very
thin" girdle is between 0.4 and 1.0 % of diameter, and Thin one is
from 1.0 to 1.5 %. (Only a part of the list is cited, the complete list has also
several other values). | | |
| | | |
| |
6.
Structure of cut parameters |
[Cut] - [End] block |
"[Cut]"
- "[end]" blocks define what parameter
range is allowed for different quality groups. There can be several "[cut]"
- "[end]" blocks inside one "[Appraiser]"
- "[end]" block. Each one is typically
for one cut type, which can be determined by "Name: ..." line, e.g.
"Name: Brilliant" or "Name: Pear", etc. The
following elements (lines) can be present in a "[cut]"
- "[end]" block (they will be described
in more details below): | "Name:
..." | - sets
the cut type (or types) which this section refers | | "Quality:
..." | - lists
quality groups that are applicable for this cut type(s) |
| "Parameters: ..." | -
names all parameters that will be defined in "Mass:..." line |
| "Mass: ..." | -
defines the range of mass and then all quality groups for that range |
Note that some of the elements may be "long"
lines, i.e. several lines that all except the last are ended by "\" (backslash).
The software treat such "long" lines as a single one. "Quality"..."
line may look like "Quality:
2A 2B 3A 3B 4A 4B"
(the example
is taken from AGA appraiser, data for Pear cut). Six values of quality will be
used for appraising, they are delimited by spaces.
"Parameters:..."
line can begin like "Parameters:
UpAngle (°) DownHeight_GIA (%) GirdleHeight_mm (s) ..."
(the example is taken from GIA appraiser). It means that
the diamond parameters will be listed in the following order: Crown angle in degrees,
Pavilion depth in percents of diameter, Girdle thickness as one of values listed
in translation table, etc. When the names of parameters does not seem clear, assume
that "Up" prefix means the crown and "Down" refers to the pavilion.
For example, "DownAngle" is a pavilion angle and "DownHeight_GIA" means
pavilion depth measured according to GIA guidelines. Look at the units of measurement
located in parenthesis next to the parameter name. "(%)" is percents of the diameter,
"(mm)" is millimeters, "(.)" is no unit and "(s)" is a value taken
from a translation table. Examples: "Table (%)" is a table diameter measured
in percents of the girdle diameter, "Culet_mm (s)" is a culet type according
to a translation table, "GirdleRatio (.)" is a ratio between maximum and
minimum girdle diameters. "Mass: ..."
line structure can be seen with this example taken from the Russian TU appraiser
for Marquise cut: 30
35 39 42 1.50 3.00 55 65 1.7 2.4 10 25 \
30 36 39 42 0.70 3.00 55 65 1.6
2.6 10 25 As the software uses "\" symbol
as a command to glue this line and a next one, all three lines above are combined
into a single "long" line, so there is only one line for the software. However,
the shipped version of Appraise.txt has the values formatted for better readability.
Namely, the first line above ("Mass 0.00 0.49 \") means that the table
below is valid for mass range from 0 to 0.49 carats only (remember, applicability
of the table is restricted by the cut type also.
The cut type is specified by "Name: ..." line).
Then the table follows which line refers to a quality value. Look at the "Quality:
..." line in the same "[cut]" -
"[end]" block to understand which
line is for which quality grade. In our case, the line "Quality: A B" means that
the second line above (one beginning with "30 35 ...") is for A quality
and the last one is for B quality. To understand data in the line, look at the
"Parameters: ..." line in the same "[cut]"
- "[end]" block. Each parameter
will correspond to two data values (minimum and aximum one). In this case, the
parameters are defined by "Parameters: UpAngle (°) DownAngle (°)...".
Given that information, the line "30 35 39 42..."
translates to: "A quality group in Russian TU appraiser for Marquise cut corresponds
to Crown angle (UpAngle) in the range from 30 to 35 degrees, to Pavilion angle
(DownAngle) between 39 and 42 degrees, etc." | | |
| | | |
| |
| |  |
| |
