![]() |
![]()
| ![]() |
![]()
NAMEgdiff - a BRL-CAD differential geometry comparator SYNOPSISgdiff [options...] left_model.g [ancestor_model.g] right_model.g DESCRIPTIONgdiff compares BRL-CAD models specified on the command line, reporting differences according to the specified options. It supports a plain "diff" comparison between two files, as well as a "3-way" comparison that accepts a third file with "ancestral" information that provides a context for the left and right files. The following options are recognized: -a (two-way diff) Report objects added in right_model.g
(three-way diff) Report objects added in left_model.g and/or right_model.g -d (two-way diff) Report objects deleted in right_model.g
(three-way diff) Report objects deleted in left_model.g and/or right_model.g -m (two-way diff) Report objects modified in right_model.g
(three-way diff) Report objects that are different in left_model.g and/or right_model.g relative to ancestor.g -q Decrease the verbosity of the output. Additional
specifications will further decrease the output provided. (Opposite effect of
v option.) All settings for this option will respect other constraints
applied to the reporting output.
-u (two-way diff) Report objects that are identical in
left_model.g and right_model.g
(three-way diff) Report objects that are identical in ancestor_model.g, left_model.g and right_model.g -v Increase the verbosity of the output. Additional
specifications will further increase the output provided. (Opposite effect of
q option.) All settings for this option will respect other constraints
applied to the reporting output.
-t # Set a numerical comparison tolerance used to compare
numerical properties. Default value is RT_LEN_TOL, but be aware that this
comparison is not aware of units.
-F "filter_string" Apply filters to the diff output, using the same set of
filters available in the search command's search. See the search
manual page for more details.
-M merged_file.g Merge the files being diffed into one output file.
The program returns 0 if the files being compared have no differences that satisfy the user-supplied options, otherwise it returns the total number of differing objects that do satisfy the supplied options. Default is to report all differences that rise above RT_LEN_TOL. EXAMPLESExample 1. Default Diffing Results Running the default options on two pre-prepared examples of Moss World gives us a summary of the status of various objects:
'M' denotes an object that was modified, 'D' is an object that was deleted, and 'A' is an object that was added. Example 2. Alternate Diffing Result Outputs The v and q options provide various styles of output, as follows: -qq (no output except the return code):
-q:
Objects are reported in lists, categorized by their status. (default):
If verbosity is not specified, this is the default output. -v:
The first elevated verbosity level is a more detailed version of the previous setting, with each parameter in the modified objects reported in detail. '-' lines show what was removed for a given attribute or parameter, and '+' lines contain the data that replaced them. -vv:
The second elevation of the verbosity level is a fully detailed diff that contains all information added or removed. Example 3. Filtering Based on Difference Type The options a, d, m, and u control which categories of diff results (added, deleted, modified, and unchanged) are reported. By default added, deleted and modified items are reported, but once one of these four options is specified only those specified are reported: Report only objects added:
Report only objects deleted:
Report both added and deleted objects, but not modified objects:
Report unmodified objects:
Example 4. Filtering Results With Tolerance To eliminate differences in modifications that are too small to be of interest, the t is used. What difference constitutes "too small" is up to the user - in this example, we will use 30 millimeters:
Notice that ellipse.s, which was on earlier lists, is now filtered out. cone.s has a difference in the x coordinates of the parameter V that is large enough to satisfy the tolerance filter, so that parameter stays in. Parameters that are not strictly numerical comparisons, or those that are part of added or deleted objects, remain in the report. Example 5. Filtering Results With Search Filters The search filtering technique can be used to select specific subsets of the database to see in reports, using the F option. For example, limiting the diff report to only objects of type elliptical torus:
Note that this option will work at all levels of verbosity:
Example 6. Combining Multiple Filters The various diff filters can be used together. For example, repeating the search filter with ell types added to the accepted list produces the following:
If we now add the tolerance filter, we see ellipse.s is filtered out:
ellipse.s satisfies the search filter, but is filtered by virtue of having no differences larger than 30 in its parameters. Example 7. Three Way Differences A "3-way" diff uses an ancestor file as a basis for evaluating the differences between two other files. This ancestor provides a "context" in which it is possible to tell whether a difference between two files is a) the product of a change in one but not the other in comparison to the original or b) whether both have (incompatibly) changed in comparison to the original. For example, if we compare moss2.g from the previous examples to a new file moss3.g:
All we can tell is that these objects differ from each other. If, however, we add moss.g to the comparison as an ancestor file:
We can now see that ellipse.r was deleted only from the right file (moss3.g) and was unchanged in moss2.g. Similarly, we can tell that LIGHT wsa deleted from moss2.g, ellipse2.r was added in moss3.g, tgc_new.s was added identically in both moss2.g and moss3.g, and eto.s is different in moss2.g and moss3.g in some fashion that the ancestor file moss.g cannot help gdiff resolve (a conflict, denoted by 'C'.) To delve deeper into the nature of the changes, we increase the verbosity with the v option:
At this level of verbosity, we can now see that most of the modifications are from the left (moss2.g) file. M(L) denotes a change that is present only in the left file - the right (moss3.g) agrees with the ancestor. Similarly, we can now see that the deletion of ellipse.r, the addition of ellipse2.r and the change to all.g come from moss3.g. The conflict on eto.s is that two add operations (one in moss2.g, one in moss3.g) produced different eto.s primitives - there is no ancestor for eto.s in moss.g, so there is no way to identify one of the eto.s primitives as "correct" - they have equal standing, and manual intervention is needed to determine which eto.s is the "correct" version. Example 8. Complex Three Way Differences Conflicts can arise from situations other than incompatible additions - an incompatible modification is also enough to trigger a conflict. Consider three ellipsoids, one of which is an ancestor, one of which has had its A and B vectors modified, and the other of which has had its B and C vectors modified. A three-way diff of these files reports a conflict:
However, closer inspection reveals that this conflict is different than the one reported above for the eto.s object:
This notation indicates that a modification in the left side (ell_1.g) does not match a modification made in ell_2.g. Unlike the eto.s, which reported an add conflict, this is a modification conflict triggered by incompatible, different parameters. Indeed a full verbosity inspection:
reveals that the changes to the A and C parameters are not in conflict - it is the B parameter that is causing the problem. Example 9. Merging Files The last and most powerful feature of gdiff is to merge two or three different geometry files into a single output file. This is most useful when an ancestor is available and a three way merge can be performed - in the two way case, the "ancestor" is an empty file and the results will tend to include many more conflicts. For example, the three way merge of the moss examples earlier:
The resulting file has only two conflict objects present - the same eto.s issue that was discussed earlier. Trying to do the same merge without the ancestor file:
The result is far less clean, although the merge was still performed - in this latter case, the end user will have to resolve many more conflicting object states manually. SEE ALSOsearch(n) AUTHORBRL-CAD Team COPYRIGHTThis software is Copyright (c) 2014-2021 by the United States Government as represented by U.S. Army Research Laboratory. BUG REPORTSReports of bugs or problems should be submitted via electronic mail to devs@brlcad.org
|