SEGYImport documentation incomplete/inconsistent (legal values, default values)
The comments here refer to the documentation of SEGYImport
and the deep dive. I found some things that are inconsistent or easy to overlook depending on how one works with the tools provided by OpenVDS.
CLI help
I find that documentation of SEGYImport
in the terminal is lacking important information. I tend to use the terminal a lot and thus also use SEGYImport --help
frequently.
The documentation of valid input values is a bit inconsistent. For some options (attribute name, attribute unit...) the output shows the accepted options.
...
--attribute-name <string>
The name of the primary VDS channel. The
name may be Amplitude (default), Attribute,
Depth, Probability, Time, Vavg, Vint, or
Vrms (default: Amplitude)
--attribute-unit <string>
The units of the primary VDS channel. The
unit name may be blank (default), ft, ft/s,
Hz, m, m/s, ms, or s
...
However, for "brick size" and "level of detail" levels the limits are not mentioned:
...
-b, --brick-size <value> The brick size for the volume data store.
--lod-levels <value> The number of LODs to generate.
...
When digging a bit deeper in the, developer documentation might even give the expectation that one should be allowed to use larger brick sizes that currently allowed. I assume that brick sizes >256 are only useful for 2D datasets. For level of detail levels, it is explained in the deep dive that the value can be at at least 0 and at most 12.
Additionally to that, neither does the documentation directly mention that the brick size has to be (certain) powers of two.
The output neither states the default value of the number of LODs. I expected that it would be zero as there is no general recommendation for number of levels in the deep dive (see also comment below).
The output of SEGYImport --help
also deviates slightly from the documentation on the homepage. I am not sure if it would be possible to synchonize the content of the README with the actual SEGYImport
output.
There might be further options with incomplete documentation.
Deep dive
Margin
It is unclear to me what the correct margin size to chose is and what the actual default is without looking into the source code of SEGYImport
. In the deep dive it is mentioned that a margin of 4 should be used as default and that the value is important when working with level of details. No connection to wavelets is mentioned.
In the README it mentions that the default value for the margin is 0 and 4 if one uses wavelet compression. Checking the source code confirms the statement of the README.
Level of detail
It is explained when one should use level of details, but no general recommendation for how many level of detail levels one should generate is given (except if one wants to use FAST). However, SEGYImport
chooses 2 as general default and 4 for poststack data.