Index: Damkjer/Damkjer_Research.sln =================================================================== --- Damkjer/Damkjer_Research.sln (revision 10) +++ Damkjer/Damkjer_Research.sln (revision 12) @@ -6,11 +6,23 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SpatialIndexing", "SpatialIndexing", "{3411130C-FC3A-47AD-9277-EEA9BDA15D28}" EndProject -Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "VpTreeAPI", "Util\SpatialIndexing\VpTree\VpTreeAPI.vcxproj", "{2738EE40-D034-9113-3C3F-2AD5946B372D}" -EndProject -Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "Util", "Util\Util.vcxproj", "{20FE2624-C64F-D61A-BD8F-1725A8E68A42}" -EndProject Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "test", "test", "{3093F2E8-7C3B-4B90-8E92-C0C235FB979A}" EndProject -Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "test_TestCase", "Util\UnitTest\test\TestUnitTest.vcxproj", "{72785A79-5BD2-AAE4-6386-93F74C7E248D}" +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "config", "config", "{CE6D9671-3679-4D3C-9665-ED738338CEDD}" + ProjectSection(SolutionItems) = preProject + config\doxyfile.txt = config\doxyfile.txt + config\doxyfilter.pl = config\doxyfilter.pl + config\m2cpp.pl = config\m2cpp.pl + EndProjectSection +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{5A0EE001-12C0-444E-9DEE-7C546B3C7256}" + ProjectSection(SolutionItems) = preProject + Top.dox = Top.dox + EndProjectSection +EndProject +Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{A1B0D6A4-C217-4E4D-8832-EB81D59F2283}" + ProjectSection(SolutionItems) = preProject + Util.bib = Util.bib + Util\Util.dox = Util\Util.dox + EndProjectSection EndProject Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "test_Exception", "Util\Exception\test\TestException.vcxproj", "{75486221-5693-30A9-18E4-ECC307F92A68}" @@ -18,7 +30,11 @@ Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "test_Metrics", "Util\SpatialIndexing\Metrics\test\TestMetrics.vcxproj", "{FF08AA20-7D15-AEAB-9915-1FA343E8C993}" EndProject +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "test_TestCase", "Util\UnitTest\test\TestUnitTest.vcxproj", "{72785A79-5BD2-AAE4-6386-93F74C7E248D}" +EndProject Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "test_VpTree", "Util\SpatialIndexing\VpTree\test\TestVpTree.vcxproj", "{84624C89-966E-4948-1393-64F0D0965AC0}" EndProject -Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{5EF24E30-9F04-4295-B259-14A8ACB6B945}" +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "Util", "Util\Util.vcxproj", "{20FE2624-C64F-D61A-BD8F-1725A8E68A42}" +EndProject +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "VpTreeAPI", "MATLAB\VpTreeAPI\VpTreeAPI.vcxproj", "{1B676DFD-587D-21CB-803A-A85006F79AEC}" EndProject Global @@ -29,4 +45,6 @@ Debug|Win32 = Debug|Win32 Debug|x64 = Debug|x64 + DebugOMP|Win32 = DebugOMP|Win32 + DebugOMP|x64 = DebugOMP|x64 OpenMP|Win32 = OpenMP|Win32 OpenMP|x64 = OpenMP|x64 @@ -35,44 +53,12 @@ EndGlobalSection GlobalSection(ProjectConfigurationPlatforms) = postSolution - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Debug|Win32.ActiveCfg = Debug|Win32 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Debug|Win32.Build.0 = Debug|Win32 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Debug|x64.ActiveCfg = Debug|x64 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Debug|x64.Build.0 = Debug|x64 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.OpenMP|Win32.Build.0 = OpenMP|Win32 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.OpenMP|x64.ActiveCfg = OpenMP|x64 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.OpenMP|x64.Build.0 = OpenMP|x64 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Release|Win32.ActiveCfg = Release|Win32 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Release|Win32.Build.0 = Release|Win32 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Release|x64.ActiveCfg = Release|x64 - {2738EE40-D034-9113-3C3F-2AD5946B372D}.Release|x64.Build.0 = Release|x64 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|Win32.ActiveCfg = Debug|Win32 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|Win32.Build.0 = Debug|Win32 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|x64.ActiveCfg = Debug|x64 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|x64.Build.0 = Debug|x64 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|Win32.Build.0 = OpenMP|Win32 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|x64.ActiveCfg = OpenMP|x64 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|x64.Build.0 = OpenMP|x64 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|Win32.ActiveCfg = Release|Win32 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|Win32.Build.0 = Release|Win32 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|x64.ActiveCfg = Release|x64 - {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|x64.Build.0 = Release|x64 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|Win32.ActiveCfg = Debug|Win32 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|Win32.Build.0 = Debug|Win32 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|x64.ActiveCfg = Debug|x64 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|x64.Build.0 = Debug|x64 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|Win32.Build.0 = OpenMP|Win32 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|x64.ActiveCfg = OpenMP|x64 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|x64.Build.0 = OpenMP|x64 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|Win32.ActiveCfg = Release|Win32 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|Win32.Build.0 = Release|Win32 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|x64.ActiveCfg = Release|x64 - {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|x64.Build.0 = Release|x64 {75486221-5693-30A9-18E4-ECC307F92A68}.Debug|Win32.ActiveCfg = Debug|Win32 {75486221-5693-30A9-18E4-ECC307F92A68}.Debug|Win32.Build.0 = Debug|Win32 {75486221-5693-30A9-18E4-ECC307F92A68}.Debug|x64.ActiveCfg = Debug|x64 {75486221-5693-30A9-18E4-ECC307F92A68}.Debug|x64.Build.0 = Debug|x64 + {75486221-5693-30A9-18E4-ECC307F92A68}.DebugOMP|Win32.ActiveCfg = DebugOMP|Win32 + {75486221-5693-30A9-18E4-ECC307F92A68}.DebugOMP|Win32.Build.0 = DebugOMP|Win32 + {75486221-5693-30A9-18E4-ECC307F92A68}.DebugOMP|x64.ActiveCfg = DebugOMP|x64 + {75486221-5693-30A9-18E4-ECC307F92A68}.DebugOMP|x64.Build.0 = DebugOMP|x64 {75486221-5693-30A9-18E4-ECC307F92A68}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 {75486221-5693-30A9-18E4-ECC307F92A68}.OpenMP|Win32.Build.0 = OpenMP|Win32 @@ -87,4 +73,8 @@ {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.Debug|x64.ActiveCfg = Debug|x64 {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.Debug|x64.Build.0 = Debug|x64 + {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.DebugOMP|Win32.ActiveCfg = DebugOMP|Win32 + {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.DebugOMP|Win32.Build.0 = DebugOMP|Win32 + {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.DebugOMP|x64.ActiveCfg = DebugOMP|x64 + {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.DebugOMP|x64.Build.0 = DebugOMP|x64 {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.OpenMP|Win32.Build.0 = OpenMP|Win32 @@ -95,8 +85,28 @@ {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.Release|x64.ActiveCfg = Release|x64 {FF08AA20-7D15-AEAB-9915-1FA343E8C993}.Release|x64.Build.0 = Release|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|Win32.ActiveCfg = Debug|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|Win32.Build.0 = Debug|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|x64.ActiveCfg = Debug|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Debug|x64.Build.0 = Debug|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.DebugOMP|Win32.ActiveCfg = DebugOMP|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.DebugOMP|Win32.Build.0 = DebugOMP|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.DebugOMP|x64.ActiveCfg = DebugOMP|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.DebugOMP|x64.Build.0 = DebugOMP|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|Win32.Build.0 = OpenMP|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|x64.ActiveCfg = OpenMP|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.OpenMP|x64.Build.0 = OpenMP|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|Win32.ActiveCfg = Release|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|Win32.Build.0 = Release|Win32 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|x64.ActiveCfg = Release|x64 + {72785A79-5BD2-AAE4-6386-93F74C7E248D}.Release|x64.Build.0 = Release|x64 {84624C89-966E-4948-1393-64F0D0965AC0}.Debug|Win32.ActiveCfg = Debug|Win32 {84624C89-966E-4948-1393-64F0D0965AC0}.Debug|Win32.Build.0 = Debug|Win32 {84624C89-966E-4948-1393-64F0D0965AC0}.Debug|x64.ActiveCfg = Debug|x64 {84624C89-966E-4948-1393-64F0D0965AC0}.Debug|x64.Build.0 = Debug|x64 + {84624C89-966E-4948-1393-64F0D0965AC0}.DebugOMP|Win32.ActiveCfg = DebugOMP|Win32 + {84624C89-966E-4948-1393-64F0D0965AC0}.DebugOMP|Win32.Build.0 = DebugOMP|Win32 + {84624C89-966E-4948-1393-64F0D0965AC0}.DebugOMP|x64.ActiveCfg = DebugOMP|x64 + {84624C89-966E-4948-1393-64F0D0965AC0}.DebugOMP|x64.Build.0 = DebugOMP|x64 {84624C89-966E-4948-1393-64F0D0965AC0}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 {84624C89-966E-4948-1393-64F0D0965AC0}.OpenMP|Win32.Build.0 = OpenMP|Win32 @@ -107,4 +117,36 @@ {84624C89-966E-4948-1393-64F0D0965AC0}.Release|x64.ActiveCfg = Release|x64 {84624C89-966E-4948-1393-64F0D0965AC0}.Release|x64.Build.0 = Release|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|Win32.ActiveCfg = Debug|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|Win32.Build.0 = Debug|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|x64.ActiveCfg = Debug|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Debug|x64.Build.0 = Debug|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.DebugOMP|Win32.ActiveCfg = DebugOMP|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.DebugOMP|Win32.Build.0 = DebugOMP|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.DebugOMP|x64.ActiveCfg = DebugOMP|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.DebugOMP|x64.Build.0 = DebugOMP|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|Win32.Build.0 = OpenMP|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|x64.ActiveCfg = OpenMP|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.OpenMP|x64.Build.0 = OpenMP|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|Win32.ActiveCfg = Release|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|Win32.Build.0 = Release|Win32 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|x64.ActiveCfg = Release|x64 + {20FE2624-C64F-D61A-BD8F-1725A8E68A42}.Release|x64.Build.0 = Release|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Debug|Win32.ActiveCfg = Debug|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Debug|Win32.Build.0 = Debug|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Debug|x64.ActiveCfg = Debug|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Debug|x64.Build.0 = Debug|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.DebugOMP|Win32.ActiveCfg = DebugOMP|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.DebugOMP|Win32.Build.0 = DebugOMP|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.DebugOMP|x64.ActiveCfg = DebugOMP|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.DebugOMP|x64.Build.0 = DebugOMP|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.OpenMP|Win32.ActiveCfg = OpenMP|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.OpenMP|Win32.Build.0 = OpenMP|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.OpenMP|x64.ActiveCfg = OpenMP|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.OpenMP|x64.Build.0 = OpenMP|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Release|Win32.ActiveCfg = Release|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Release|Win32.Build.0 = Release|Win32 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Release|x64.ActiveCfg = Release|x64 + {1B676DFD-587D-21CB-803A-A85006F79AEC}.Release|x64.Build.0 = Release|x64 EndGlobalSection GlobalSection(SolutionProperties) = preSolution @@ -113,10 +155,11 @@ GlobalSection(NestedProjects) = preSolution {3411130C-FC3A-47AD-9277-EEA9BDA15D28} = {27DB8DBD-623B-4593-80F3-9F25F07BBA1A} + {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} = {27DB8DBD-623B-4593-80F3-9F25F07BBA1A} + {A1B0D6A4-C217-4E4D-8832-EB81D59F2283} = {27DB8DBD-623B-4593-80F3-9F25F07BBA1A} {20FE2624-C64F-D61A-BD8F-1725A8E68A42} = {27DB8DBD-623B-4593-80F3-9F25F07BBA1A} - {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} = {27DB8DBD-623B-4593-80F3-9F25F07BBA1A} - {2738EE40-D034-9113-3C3F-2AD5946B372D} = {3411130C-FC3A-47AD-9277-EEA9BDA15D28} - {72785A79-5BD2-AAE4-6386-93F74C7E248D} = {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} + {1B676DFD-587D-21CB-803A-A85006F79AEC} = {3411130C-FC3A-47AD-9277-EEA9BDA15D28} {75486221-5693-30A9-18E4-ECC307F92A68} = {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} {FF08AA20-7D15-AEAB-9915-1FA343E8C993} = {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} + {72785A79-5BD2-AAE4-6386-93F74C7E248D} = {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} {84624C89-966E-4948-1393-64F0D0965AC0} = {3093F2E8-7C3B-4B90-8E92-C0C235FB979A} EndGlobalSection Index: Damkjer/PointProcessing/SpatialAnalyzer/spanalyze.m =================================================================== --- Damkjer/PointProcessing/SpatialAnalyzer/spanalyze.m (revision 9) +++ Damkjer/PointProcessing/SpatialAnalyzer/spanalyze.m (revision 12) @@ -1,8 +1,47 @@ -% -% [CLASSES] = SPANALYZE(QUERIES, DATABASE, ...) -% -% Attribute points by eigen analysis. -% -% Copyright 2012 Kristian L. Damkjer +% SpAnalyze Point Cloud Spatial Analysis +% +% File: spanalize.m +% +% Description: +% Perform local feature attribution via eigenspace analysis. +% +% Limitations: +% No known limitations. +% +% Synopsis: +% [classes] = spanalyse(queries, database, ...) +% +% Inputs: +% queries - . +% database - . +% +% Option strings may be provided as abbreviations as long as they resolve to +% a unique option. +% +% 'neighbors' - . +% 'radius' - . +% 'counts' - . +% 'steps' - . +% +% Outputs: +% classes - Structure containing the spatial analysis classifications. +% +% Toolbox requirements: +% None. +% +% Code requirements: +% None. +% +% Data requirements: +% None. +% +% References: +% None. +% +% See Also: +% None. +% + +% Copyright (C) 2013 Kristian L. Damkjer. % % Software History: @@ -13,407 +52,441 @@ % -function [ CLASSES ] = spanalyze( QUERIES, DATABASE, varargin ) -% Parse Inputs -userParams = parseInputs(varargin{:}); - -dimensions=size(QUERIES, 1); -elements=size(QUERIES, 2); - -norms=zeros(size(QUERIES)); -feats=zeros(size(QUERIES)); - -biases=zeros(1,elements); - -ints=zeros(1,elements); - -msg='Computing Structure Tensors...'; -tstart=tic; -h = timebar(1, elements, msg, tstart); - -%step=8192; -step=1000; -tic; - -for elem=1:step:elements - - last=min(elem+step-1,elements); - - % Get the nearest neighbors of elem - if (userParams.radius > 0 && userParams.neighbors <= 0) - % Perform a fixed radius search - NN=DATABASE.rnn(QUERIES(:,elem:last),... - userParams.radius); - elseif (userParams.radius <= 0 && userParams.neighbors > 0) - % Search unconstrained neighbors - NN=DATABASE.knn(QUERIES(:,elem:last),... - userParams.neighbors); - elseif (userParams.radius > 0 && userParams.neighbors > 0) - % Search constrained to radius - NN=DATABASE.knn(QUERIES(:,elem:last),... - userParams.neighbors,... - 'lim',userParams.radius); - elseif (~isempty(userParams.counts) && userParams.radius <= 0) - % Search unconstrained neighbors - NN=DATABASE.knn(QUERIES(:,elem:last),... - max(userParams.counts)); - elseif (~isempty(userParams.counts) && userParams.radius > 0) - % Search constrained to radius - NN=DATABASE.knn(QUERIES(:,elem:last),... - max(userParams.counts),... - 'lim',userParams.radius); - elseif (~isempty(userParams.steps)) - % Perform a fixed radius search - [NN,DISTS]=DATABASE.rnn(QUERIES(:,elem:last),... - max(userParams.steps)); - end - - if (isempty(userParams.counts) && isempty(userParams.steps)) - cells=cell(1,length(NN)); - - for n=1:length(NN) - cells{n}=QUERIES(:,NN{n})'; - end - - [covs,bias,inty]=fastcov(cells); - elseif (~isempty(userParams.counts)) - tempfeats=zeros(dimensions,size(NN,1)); - tempde=zeros(length(userParams.counts),size(NN,1)); - - tempcovs=cell(length(userParams.counts),1); - tempbias=cell(length(userParams.counts),1); - tempinty=cell(length(userParams.counts),1); - - for c=1:length(userParams.counts) +%****************************************************************************** +% spanalyze +%****************************************************************************** +function [ classes ] = spanalyze( queries, database, varargin ) + % Perform local feature attribution via eigenspace analysis. + % + % Parameters: + % queries - . + % + % database - . + % + % varargin - Variable-length input argument list. Option strings may be + % provided as abbreviations as long as they resolve to a + % unique option.Defined key-value pairs include the following: + % 'neighbors' - . + % 'radius' - . + % 'counts' - . + % 'steps' - . + % + % Returns: + % classes - Structure containing the spatial analysis classifications. + % + + userParams = parseInputs(varargin{:}); % Parse Inputs + + % Sizing metrics + dimensions=size(queries, 1); + elements=size(queries, 2); + + % Pre-allocate classes + norms=zeros(size(queries)); + feats=zeros(size(queries)); + biases=zeros(1,elements); + ints=zeros(1,elements); + + % This process may take a while. Display time bar while processing. + msg='Computing Structure Tensors...'; + tstart=tic; + h = timebar(1, elements, msg, tstart); + + % Step through the queries in chunks. + step=1000; + + tic; + + for elem=1:step:elements + + % The last available element may be closer than elem + step. + last=min(elem+step-1,elements); + + % Get the nearest neighbors of elem + if (userParams.radius > 0 && userParams.neighbors <= 0) + % Perform a fixed radius search + NN=database.rnn(queries(:,elem:last),... + userParams.radius); + elseif (userParams.radius <= 0 && userParams.neighbors > 0) + % Search unconstrained neighbors + NN=database.knn(queries(:,elem:last),... + userParams.neighbors); + elseif (userParams.radius > 0 && userParams.neighbors > 0) + % Search constrained to radius + NN=database.knn(queries(:,elem:last),... + userParams.neighbors,... + 'lim',userParams.radius); + elseif (~isempty(userParams.counts) && userParams.radius <= 0) + % Search unconstrained neighbors + NN=database.knn(queries(:,elem:last),... + max(userParams.counts)); + elseif (~isempty(userParams.counts) && userParams.radius > 0) + % Search constrained to radius + NN=database.knn(queries(:,elem:last),... + max(userParams.counts),... + 'lim',userParams.radius); + elseif (~isempty(userParams.steps)) + % Perform a fixed radius search + [NN,DISTS]=database.rnn(queries(:,elem:last),... + max(userParams.steps)); + end + + % Compute neighborhood covariance, intensity and bias values. + if (isempty(userParams.counts) && isempty(userParams.steps)) + % Not using adaptive neighborhoods. cells=cell(1,length(NN)); for n=1:length(NN) - cells{n}=QUERIES(:,NN{n}(1:userParams.counts(c)))'; - end - - [tempcovs{c},tempbias{c},tempinty{c}]=fastcov(cells); - -% [tempcovs{c},tempbias{c},tempinty{c}]=fastcov(cellfun(@(x) QUERIES(:,x(1:userParams.counts(c)))',NN,'UniformOutput',false)); - - for nbr=1:size(NN,1) -% [~,D]=eig(tempcovs{c}{nbr}); - [~,D]=par_eig(tempcovs{c}{nbr}); - tempfeats(:,nbr)=sort(diag(D),'descend'); - end - - % Compute dimensional degree - tempdims=(tempfeats(1:dimensions-1,:)-tempfeats(2:dimensions,:))./... - repmat(tempfeats(1,:),dimensions-1,1); - - % Compute isotropy - tempiso=(tempfeats(dimensions,:))./(tempfeats(1,:)); - - % Compute dimensional entropy - tempalpha=[tempdims;tempiso]; - tempde(c,:)=-sum(tempalpha.*log(tempalpha))./log(dimensions); - end - - [~,ind]=min(tempde); - - covs=tempcovs{ind}; - bias=tempbias{ind}; - inty=tempinty{ind}; - elseif (~isempty(userParams.steps)) - tempfeats=zeros(dimensions,size(NN,1)); - tempde=zeros(length(userParams.steps),size(NN,1)); - - tempcovs=cell(length(userParams.steps),1); - tempbias=cell(length(userParams.steps),1); - tempinty=cell(length(userParams.steps),1); - - for c=1:length(userParams.steps) - - nbrs=cell(1,length(DISTS)); - - for n=1:length(DISTS) - nbrs{n}=sum(DISTS{n} <= userParams.steps(c))'; - end - -% nbrs=cellfun(@(x) sum(x <= userParams.steps(c))',DISTS,'UniformOutput',false); - - cells=cell(1,length(NN)); - - for n=1:length(NN) - cells{n}=QUERIES(:,NN{n}(DISTS{n} <= userParams.steps(c)))'; - end - -% [tempcovs{c},tempbias{c},tempinty{c}]=fastcov(cellfun(@(x,y) QUERIES(:,x(y <= userParams.steps(c)))',NN,DISTS,'UniformOutput',false)); - - [tempcovs{c},tempbias{c},tempinty{c}]=fastcov(cells); - - for nbr=1:size(NN,1) - if (nbrs{nbr}<5) - continue; + cells{n}=queries(:,NN{n})'; + end + + [covs,bias,inty]=fastcov(cells); + elseif (~isempty(userParams.counts)) + % Using variable neighbor count based adaptive neighborhoods. + + % TODO: Conoslidate the common functionality in adaptive methods into + % a single function. + + tempfeats=zeros(dimensions,size(NN,1)); + tempde=zeros(length(userParams.counts),size(NN,1)); + + tempcovs=cell(length(userParams.counts),1); + tempbias=cell(length(userParams.counts),1); + tempinty=cell(length(userParams.counts),1); + + % Compute candidiate values (HACKY) + for c=1:length(userParams.counts) + cells=cell(1,length(NN)); + + for n=1:length(NN) + cells{n}=queries(:,NN{n}(1:userParams.counts(c)))'; end - -% [~,D]=eig(tempcovs{c}{nbr}); - [~,D]=par_eig(tempcovs{c}{nbr}); - tempfeats(:,nbr)=sort(diag(D),'descend'); - end - - % Compute dimensional degree - % Do not use the following definition based on singular values: - % tempdims=(sqrt(tempfeats(1:dimensions-1,:))-sqrt(tempfeats(2:dimensions,:)))./... - % repmat(sqrt(tempfeats(1,:)),dimensions-1,1); - - tempdims=(tempfeats(1:dimensions-1,:)-tempfeats(2:dimensions,:))./... - repmat(tempfeats(1,:),dimensions-1,1); - - % Compute isotropy - tempiso=(tempfeats(dimensions,:))./(tempfeats(1,:)); - - % Compute dimensional entropy - tempalpha=[tempdims;tempiso]; - tempde(c,:)=-sum(tempalpha.*log(tempalpha))./log(dimensions); - end - - [~,ind]=nanmin(tempde); - - covs=tempcovs{ind}; - bias=tempbias{ind}; - inty=tempinty{ind}; - - else - error('What?!'); - end - -% Same solution via SVD appears to be slower based on emperical testing -% recentered=fastcenter(cellfun(@(x) QUERIES(:,x)',NN,'UniformOutput',false)); - -% disp('covs'); -% cellfun(@(x) disp(x),covs); - - rad=userParams.radius; - - [V,D]=par_eig(covs); - - for nbr=1:size(NN,1) - % skip underconstrained (possible with radius searches) - if (rad > 0 && (length(NN{nbr})<5 || any(any(isnan(covs{nbr}))))) - continue; - end - -% maxnbrs=max(maxnbrs,length(NN{nbr})); - -% [V,D]=eig(covs{nbr}); -% [~,index]=min(diag(D)); -% [~,index]=min(D{nbr}); -% norms(:,elem+nbr-1)=abs(V(:,index)) .* sqrt(D(index, index)); -% norms(:,elem+nbr-1)=abs(V(:,index)); -% norms(:,elem+nbr-1)=abs(V{nbr}(:,index)); - - A=V{nbr}; - norms(:,elem+nbr-1)=abs(A(:,end)); - - % Define features as eigenvalues - % feats(:,elem+nbr-1)=sort(diag(D),'descend'); - - % Define features as singular values -% feats(:,elem+nbr-1)=sqrt(sort(diag(D),'descend')); -% feats(:,elem+nbr-1)=sqrt(sort(D{nbr},'descend')); - feats(:,elem+nbr-1)=sqrt(D{nbr}); - - biases(elem+nbr-1)=bias{nbr}; - ints(elem+nbr-1)=inty{nbr}; - -% Same solution via SVD appears to be slower via emperical testing -% [~,S,V]=svd(recentered{nbr},0); -% S = S ./ sqrt(length(NN{nbr})-1); -% norms(:,elem+nbr-1)=abs(V(:,dimensions) .* S(dimensions, dimensions)); -% feats(:,elem+nbr-1)=diag(S).^2; - - end - - if (toc > 1) - tic; - h = timebar(elem, elements, msg, tstart, h); - end + + [tempcovs{c},tempbias{c},tempinty{c}]=fastcov(cells); + + for nbr=1:size(NN,1) + [~,D]=par_eig(tempcovs{c}{nbr}); + tempfeats(:,nbr)=sort(diag(D),'descend'); + end + + % Compute dimensional degree + % Do not use the following definition based on singular values: + % tempdims=(sqrt(tempfeats(1:dimensions-1,:))-... + % sqrt(tempfeats(2:dimensions,:)))./... + % repmat(sqrt(tempfeats(1,:)),dimensions-1,1); + tempdims=(tempfeats(1:dimensions-1,:)-... + tempfeats(2:dimensions,:))./... + repmat(tempfeats(1,:),dimensions-1,1); + + % Compute isotropy + tempiso=(tempfeats(dimensions,:))./(tempfeats(1,:)); + + % Compute dimensional entropy + tempalpha=[tempdims;tempiso]; + tempde(c,:)=-sum(tempalpha.*log(tempalpha))./log(dimensions); + end + + % Minimize on dimensional entropy (HACKY) + [~,ind]=min(tempde); + + covs=tempcovs{ind}; + bias=tempbias{ind}; + inty=tempinty{ind}; + elseif (~isempty(userParams.steps)) + % Using variable neighborhood radii based adaptive neighborhoods. + + % TODO: Conoslidate the common functionality in adaptive methods into + % a single function. + + tempfeats=zeros(dimensions,size(NN,1)); + tempde=zeros(length(userParams.steps),size(NN,1)); + + tempcovs=cell(length(userParams.steps),1); + tempbias=cell(length(userParams.steps),1); + tempinty=cell(length(userParams.steps),1); + + % Compute candidiate values (HACKY) + for c=1:length(userParams.steps) + + nbrs=cell(1,length(DISTS)); + + for n=1:length(DISTS) + nbrs{n}=sum(DISTS{n} <= userParams.steps(c))'; + end + + cells=cell(1,length(NN)); + + for n=1:length(NN) + cells{n}=queries(:,NN{n}(DISTS{n} <= userParams.steps(c)))'; + end + + [tempcovs{c},tempbias{c},tempinty{c}]=fastcov(cells); + + for nbr=1:size(NN,1) + if (nbrs{nbr}<5) + continue; + end + + [~,D]=par_eig(tempcovs{c}{nbr}); + tempfeats(:,nbr)=sort(diag(D),'descend'); + end + + % Compute dimensional degree + % Do not use the following definition based on singular values: + % tempdims=(sqrt(tempfeats(1:dimensions-1,:))-... + % sqrt(tempfeats(2:dimensions,:)))./... + % repmat(sqrt(tempfeats(1,:)),dimensions-1,1); + tempdims=(tempfeats(1:dimensions-1,:)-... + tempfeats(2:dimensions,:))./... + repmat(tempfeats(1,:),dimensions-1,1); + + % Compute isotropy + tempiso=(tempfeats(dimensions,:))./(tempfeats(1,:)); + + % Compute dimensional entropy + tempalpha=[tempdims;tempiso]; + tempde(c,:)=-sum(tempalpha.*log(tempalpha))./log(dimensions); + end + + % Minimize on dimensional entropy (HACKY) + [~,ind]=nanmin(tempde); + + covs=tempcovs{ind}; + bias=tempbias{ind}; + inty=tempinty{ind}; + else + error('Unhandled Condition'); + end + + % Compute the neighborhood covariance eigenvalues. + [V,D]=par_eig(covs); + + for nbr=1:size(NN,1) + + % skip underconstrained neighborhoods (possible with radius searches) + if (userParams.radius > 0 && (length(NN{nbr})<5 ||... + any(any(isnan(covs{nbr}))))) + continue; + end + + [~,index]=min(abs(D{nbr})); + A=V{nbr}; + norms(:,elem+nbr-1)=abs(A(:,index)); + + % Option 1: Define features as eigenvalues + % feats(:,elem+nbr-1)=sort(D{nbr},'descend'); + + % Option 2: Define features as singular values. Eigenvalues are not + % guaranteed to be in any order. We want them in descending order. + feats(:,elem+nbr-1)=sqrt(sort(D{nbr},'descend')); + + biases(elem+nbr-1)=bias{nbr}; + ints(elem+nbr-1)=inty{nbr}; + end + + % Update the time bar. + if (toc > 1) + tic; + h = timebar(elem, elements, msg, tstart, h); + end + end + + % Close the time bar, if still open. + if (all(ishghandle(h, 'figure'))) + close(h); + end + + % Compute Normalized Features + energy=sum(feats,1); + nfeats=bsxfun(@times,feats',1./energy')'; + nfeats(isnan(nfeats))=1; + + % Compute Omnivariance + omnivar=prod(feats,1).^(1/dimensions); +% omnivar=prod(feats.*feats,1).^(1/dimensions); +% omnivar=prod(nfeats,1).^(1/dimensions); + + % Compute Eigen Entropy + entropy=-sum(nfeats.*log(nfeats))./log(dimensions); + entropy(entropy==1)=0; + + % Compute Eigen Structure + structure=1-entropy; + + % Compute Fractional Anisotropy + evmeans=mean(feats,1); + evdevs=feats-repmat(evmeans,dimensions,1); + numer=dimensions.*sum(evdevs.^2,1); + denom=(dimensions-1).*sum(feats.^2,1); + fa=(numer./denom).^(1/2); + + % Compute Anisotropy + ani=(feats(1,:)-feats(dimensions,:))./(feats(1,:)); + + % Compute Isotropy + iso=1-ani; + + % Compute dimensional degree + dims=zeros(size(feats)); + dims(1:dimensions-1,:)=(feats(1:dimensions-1,:)-feats(2:dimensions,:))./... + repmat(feats(1,:),dimensions-1,1); + dims(dimensions,:)=iso; + + % Compute Dimensional Embedding + [~,embed]=max([dims;iso],[],1); + + % Compute dimensional entropy + alpha=[dims;iso]; + de=-sum(alpha.*log(alpha))./log(dimensions); + + % Populate feature classes + classes.features=feats; + classes.normals=norms; + classes.dimensionality=dims; + classes.isotropy=iso; + classes.anisotropy=ani; + classes.FA=fa; + classes.entropy=entropy; + classes.structure=structure; + classes.omnivariance=omnivar; + classes.embedding=embed; + classes.biases=biases; + classes.intensity=ints; + classes.de=de; + +% TODO: Add curvature analysis back into spatial analyzer. Will require +% re-work. +% +% st=zeros(size(QUERIES)); +% +% msg='Computing Normal Structure Tensors...'; +% tstart=tic; +% h = timebar(1, elements, msg, tstart); +% +% for elem=1:step:elements +% +% last=min(elem+step-1,elements); +% +% % Get the nearest neighbors of elem +% if (userParams.neighbors <= 0) +% % Perform a fixed radius search +% NN=DATABASE.rnn(QUERIES(:,elem:last),... +% userParams.radius); +% else +% if (userParams.radius <= 0) +% % Search unconstrained +% NN=DATABASE.knn(QUERIES(:,elem:last),... +% userParams.neighbors); +% else +% % Search constrained to radius +% NN=DATABASE.knn(QUERIES(:,elem:last),... +% userParams.neighbors,... +% 'lim',userParams.radius); +% end +% end +% +% for nbr=1:size(NN,1) +% normals=norms(:,NN{nbr}); +% +% S=svd(normals',0); +% st(:,elem+nbr-1)=S.*S./(length(NN{nbr})-1); +% +% % D=eig(1/(length(NN{nbr})-1)*(normals*normals')); +% % st(:,elem+nbr-1)=sort(D,'descend'); +% +% % ST=normals*normals'; +% +% % if (nbr == 1) +% % D=eig(1/(length(NN{nbr})-1)*(normals*normals')); +% % disp('EIG:'); +% % disp(sqrt(D)); +% % +% % S=svd(normals',0); +% % S = S ./ sqrt(length(NN{nbr})-1); +% % disp('SVD:'); +% % disp(abs(S)); +% % +% % end +% +% end +% +% if(toc > 1) +% tic; +% h = timebar(elem, elements, msg, tstart, h); +% end +% end +% +% if (all(ishghandle(h, 'figure'))) +% close(h); +% end + end -% disp(maxnbrs); - -if (all(ishghandle(h, 'figure'))) - close(h); -end - -% Compute Omnivariance -omnivar=prod(feats,1).^(1/dimensions); - -% Compute Eigen Entropy -energy=sum(feats,1); -nfeats=bsxfun(@times,feats',1./energy')'; -nfeats(isnan(nfeats))=1; -entropy=-sum(nfeats.*log(nfeats))./log(dimensions); -entropy(entropy==1)=0; - -% Compute Eigen Structure -structure=1-entropy; - -% Compute Fractional Anisotropy -evmeans=mean(feats,1); -evdevs=feats-repmat(evmeans,dimensions,1); -numer=dimensions.*sum(evdevs.^2,1); -denom=(dimensions-1).*sum(feats.^2,1); -fa=(numer./denom).^(1/2); - -% Compute Anisotropy -ani=(feats(1,:)-feats(dimensions,:))./(feats(1,:)); - -% Compute Isotropy -iso=1-ani; - -% Compute dimensional degree -dims=zeros(size(feats)); -dims(1:dimensions-1,:)=(feats(1:dimensions-1,:)-feats(2:dimensions,:))./... - repmat(feats(1,:),dimensions-1,1); -dims(dimensions,:)=iso; - -% Compute Dimensional Embedding -[~,embed]=max([dims;iso],[],1); - -% Compute dimensional entropy -alpha=[dims;iso]; -de=-sum(alpha.*log(alpha))./log(dimensions); - -% Populate feature classes -%CLASSES=[feats;norms;dims;iso;ani;fa;entropy;structure;omnivar;embed;biases;ints]; -CLASSES.features=feats; -CLASSES.normals=norms; -CLASSES.dimensionality=dims; -CLASSES.isotropy=iso; -CLASSES.anisotropy=ani; -CLASSES.FA=fa; -CLASSES.entropy=entropy; -CLASSES.structure=structure; -CLASSES.omnivariance=omnivar; -CLASSES.embedding=embed; -CLASSES.biases=biases; -CLASSES.intensity=ints; -CLASSES.de=de; - -% st=zeros(size(QUERIES)); -% -% msg='Computing Normal Structure Tensors...'; -% tstart=tic; -% h = timebar(1, elements, msg, tstart); -% -% for elem=1:step:elements -% -% last=min(elem+step-1,elements); -% -% % Get the nearest neighbors of elem -% if (userParams.neighbors <= 0) -% % Perform a fixed radius search -% NN=DATABASE.rnn(QUERIES(:,elem:last),... -% userParams.radius); -% else -% if (userParams.radius <= 0) -% % Search unconstrained -% NN=DATABASE.knn(QUERIES(:,elem:last),... -% userParams.neighbors); -% else -% % Search constrained to radius -% NN=DATABASE.knn(QUERIES(:,elem:last),... -% userParams.neighbors,... -% 'lim',userParams.radius); -% end -% end -% -% for nbr=1:size(NN,1) -% normals=norms(:,NN{nbr}); -% -% S=svd(normals',0); -% st(:,elem+nbr-1)=S.*S./(length(NN{nbr})-1); -% -% % D=eig(1/(length(NN{nbr})-1)*(normals*normals')); -% % st(:,elem+nbr-1)=sort(D,'descend'); -% -% % ST=normals*normals'; -% -% % if (nbr == 1) -% % D=eig(1/(length(NN{nbr})-1)*(normals*normals')); -% % disp('EIG:'); -% % disp(sqrt(D)); -% % -% % S=svd(normals',0); -% % S = S ./ sqrt(length(NN{nbr})-1); -% % disp('SVD:'); -% % disp(abs(S)); -% % -% % end -% -% end -% -% if(toc > 1) -% tic; -% h = timebar(elem, elements, msg, tstart, h); -% end -% end -% -% if (all(ishghandle(h, 'figure'))) -% close(h); -% end - -% CLASSES = QUERIES; - -end - -% -% PARSEINPUTS Support function to parse inputs into userParams structure +%****************************************************************************** +% parseInputs +%****************************************************************************** function [userParams] = parseInputs(varargin) - -userParams = struct('radius', 0, 'neighbors', 0, 'counts', [], 'steps', []); - -if length(varargin) == 1 || ~isnumeric(varargin{2}) - value = varargin{1}; - - if (isscalar(value) && ... - isreal(value) && ... - value >= 5) - userParams.neighbors = fix(value); - else - error('Damkjer:InvalidCount', ... - ['Number of Neighbors must be a real valued positive '... - 'integer greater or equal to 5: ' num2str(value)]); - end - - varargin(1) = []; -end - -% Parse the Property/Value pairs -if rem(length(varargin), 2) ~= 0 - error('Damkjer:PropertyValueNotPair', ... - ['Additional arguments must take the form of Property/Value '... - 'pairs']); -end - -propertyNames = {'neighbors', 'radius', 'counts', 'steps'}; - -while ~isempty(varargin) - property = varargin{1}; - value = varargin{2}; - - % If the property has been supplied in a shortened form, lengthen it - iProperty = find(strncmpi(property, propertyNames, length(property))); - - if isempty(iProperty) - error('Damkjer:InvalidProperty', 'Invalid Property'); - elseif length(iProperty) > 1 - error('Damkjer:AmbiguousProperty', ... - 'Supplied shortened property name is ambiguous'); - end - - property = propertyNames{iProperty}; - - switch property + % Support function to parse inputs into userParams structure + % + % Parameters: + % varargin - Variable-length input argument list. Option strings may be + % provided as abbreviations as long as they resolve to a + % unique option.Defined key-value pairs include the following: + % 'neighbors' - . + % 'radius' - . + % 'counts' - . + % 'steps' - . + % + % Returns: + % userParams - . + + userParams = struct('radius', 0, 'neighbors', 0, 'counts', [], 'steps', []); + + if length(varargin) == 1 || ~isnumeric(varargin{2}) + value = varargin{1}; + + if (isscalar(value) && ... + isreal(value) && ... + value >= 5) + userParams.neighbors = fix(value); + else + error('Damkjer:InvalidCount', ... + ['Number of Neighbors must be a real valued positive '... + 'integer greater or equal to 5: ' num2str(value)]); + end + + varargin(1) = []; + end + + % Parse the Property/Value pairs + if rem(length(varargin), 2) ~= 0 + error('Damkjer:PropertyValueNotPair', ... + ['Additional arguments must take the form of Property/Value '... + 'pairs']); + end + + propertyNames = {'neighbors', 'radius', 'counts', 'steps'}; + + while ~isempty(varargin) + property = varargin{1}; + value = varargin{2}; + + % If the property has been supplied in a shortened form, lengthen it + iProperty = find(strncmpi(property, propertyNames, length(property))); + + if isempty(iProperty) + error('Damkjer:InvalidProperty', 'Invalid Property'); + elseif length(iProperty) > 1 + error('Damkjer:AmbiguousProperty', ... + 'Supplied shortened property name is ambiguous'); + end + + property = propertyNames{iProperty}; + + switch property case 'neighbors' if (isscalar(value) && ... isreal(value) && ... value >= 5) - userParams.neighbors = fix(value); + userParams.neighbors = fix(value); else error('Damkjer:InvalidCount', ... @@ -453,31 +526,31 @@ 'values']); end - end - - varargin(1:2) = []; + end + + varargin(1:2) = []; + end + + % Check for mutually exclusive options. + if (~isempty(userParams.counts) && userParams.neighbors >= 5) + error('Damkjer:MutExOpts', ... + '''neighbors'' and ''counts'' options are mutually exclusive'); + end + + if (~isempty(userParams.steps) && userParams.radius > 0) + error('Damkjer:MutExOpts', ... + '''steps'' and ''radius'' options are mutually exclusive'); + end + + if (~isempty(userParams.counts) && ~isempty(userParams.steps)) + error('Damkjer:MutExOpts', ... + '''steps'' and ''counts'' options are mutually exclusive'); + end + + % Default, if necessary. + if (userParams.neighbors <= 0 && ... + userParams.radius <= 0 && ... + isempty(userParams.counts) && ... + isempty(userParams.steps)) + userParams.radius = 1; + end end - -if (~isempty(userParams.counts) && userParams.neighbors >= 5) - error('Damkjer:MutExOpts', ... - '''neighbors'' and ''counts'' options are mutually exclusive'); -end - -if (~isempty(userParams.steps) && userParams.radius > 0) - error('Damkjer:MutExOpts', ... - '''steps'' and ''radius'' options are mutually exclusive'); -end - -if (~isempty(userParams.counts) && ~isempty(userParams.steps)) - error('Damkjer:MutExOpts', ... - '''steps'' and ''counts'' options are mutually exclusive'); -end - -if (userParams.neighbors <= 0 && ... - userParams.radius <= 0 && ... - isempty(userParams.counts) && ... - isempty(userParams.steps)) - userParams.radius = 1; -end - -end - Index: Damkjer/Util/Exception/Exception.cpp =================================================================== --- Damkjer/Util/Exception/Exception.cpp (revision 10) +++ Damkjer/Util/Exception/Exception.cpp (revision 12) @@ -4,7 +4,12 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: -// -// LIMITATIONS: +// DESCRIPTION: +//> The class implementations for exception classes that parallel the STL +// exception classes. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -14,8 +19,8 @@ //***************************************************************************** -#include -#include - -#include "Exception.h" +#include // HASA std::ostream interface +#include // USES std::stringstream interfaces + +#include "Exception.h" // ISA Damkjer::Exception implementation namespace Damkjer @@ -23,12 +28,9 @@ //***************************************************************************** -// Exception::~Exception -//***************************************************************************** -Util_API Exception::~Exception() throw() -{ -} - -//***************************************************************************** -// Exception::what +// Exception::what() +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< //***************************************************************************** Util_API const char* Exception::what() const throw() @@ -45,5 +47,10 @@ //***************************************************************************** -// Exception::message +// Exception::message(std::ostream&) +//> Apply standard formatting to the exception verbose message stream. +// +// @param os The output stream to receive the formatted message. +// @return The updated stream. +//< //***************************************************************************** Util_API std::ostream& Exception::message(std::ostream& os) const @@ -61,9 +68,15 @@ //***************************************************************************** -// Exception::push +// Exception::push(const std::string&, const std::string&, const int) +//> Add a record to the exception stack trace. +// +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** Util_API void Exception::push(const std::string& who, - const std::string& file, - const int line) const + const std::string& file, + const int line) const { std::ostringstream os; @@ -73,5 +86,10 @@ //***************************************************************************** -// Exception::stackTrace +// Exception::stackTrace(std::ostream&) +//> Provide a stack trace for the exceptional condition. +// +// @param os The output stream to receive the stack trace. +// @return The updated stream. +//< //***************************************************************************** Util_API std::ostream& Exception::stackTrace(std::ostream& os) const @@ -80,8 +98,4 @@ os << "\nStack Trace:"; -// os << "\nStack Trace:"; - -// BlockIndent block(79, os); -// block.indentBy(3); for (std::vector::const_iterator vsi = theStack.begin(); @@ -89,9 +103,7 @@ ++vsi) { -// block << "\n" << *vsi; os << "\n" << *vsi; } -// block << "\n"; os << "\n"; @@ -101,6 +113,14 @@ //***************************************************************************** // Exception::Exception -//***************************************************************************** -Util_API Exception::Exception(const std::string& why, +//> Allocate memory and instantiate an Exception object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< +//***************************************************************************** +Util_API +Exception::Exception(const std::string& why, const std::string& who, const std::string& file, @@ -115,6 +135,14 @@ //***************************************************************************** // Exception::insertReason -//***************************************************************************** -Util_API std::ostream& Exception::insertReason(std::ostream& os) const +//> Insert the reason for raising the exception into the output stream. +// +// @param os The output stream to receive the formatted reason for raising +// the exception. +// @return The updated stream. +//< +//***************************************************************************** +Util_API std::ostream& +Exception::insertReason(std::ostream& os) +const { return os << "\n" << theWhy << "\n"; @@ -123,4 +151,11 @@ //***************************************************************************** // LogicError::LogicError +//> Allocate memory and instantiate an LogicError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** LogicError::LogicError(const std::string& why, @@ -129,18 +164,16 @@ int line) : Exception(why, who, file, line) -// , std::logic_error(why) -{ -} - -//***************************************************************************** -// LogicError::what -//***************************************************************************** -//const char* LogicError::what() const throw() -//{ - //return Exception::what(); -//} +{ +} //***************************************************************************** // DomainError::DomainError +//> Allocate memory and instantiate an DomainError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** DomainError::DomainError(const std::string& why, @@ -155,6 +188,12 @@ //***************************************************************************** // DomainError::what -//***************************************************************************** -const char* DomainError::what() const throw() +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< +//***************************************************************************** +const char* +DomainError::what() +const throw() { return Exception::what(); @@ -163,4 +202,11 @@ //***************************************************************************** // InvalidArgument::InvalidArgument +//> Allocate memory and instantiate an InvalidArgument object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** InvalidArgument::InvalidArgument(const std::string& why, @@ -175,6 +221,12 @@ //***************************************************************************** // InvalidArgument::what -//***************************************************************************** -const char* InvalidArgument::what() const throw() +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< +//***************************************************************************** +const char* +InvalidArgument::what() +const throw() { return Exception::what(); @@ -183,4 +235,11 @@ //***************************************************************************** // LengthError::LengthError +//> Allocate memory and instantiate an LengthError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** LengthError::LengthError(const std::string& why, @@ -195,4 +254,8 @@ //***************************************************************************** // LengthError::what +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< //***************************************************************************** const char* LengthError::what() const throw() @@ -203,4 +266,11 @@ //***************************************************************************** // OutOfRange::OutOfRange +//> Allocate memory and instantiate an OutOfRange object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** OutOfRange::OutOfRange(const std::string& why, @@ -215,4 +285,8 @@ //***************************************************************************** // OutOfRange::what +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< //***************************************************************************** const char* OutOfRange::what() const throw() @@ -223,4 +297,15 @@ //***************************************************************************** // RethrowError::RethrowError +//> Allocate memory and instantiate an RethrowError object with details. +// +// This constructor is used to wrap a std::exception as a Damkjer::Exception +// for the purpose of rethrowing. The what() portion of the std::exception +// is reported in the what() of the RethrowError. +// +// @param thrown The original thrown std::exception to be re-thrown. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** RethrowError::RethrowError(const std::exception& thrown, @@ -236,4 +321,11 @@ //***************************************************************************** // RuntimeError::RuntimeError +//> Allocate memory and instantiate an RuntimeError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** RuntimeError::RuntimeError(const std::string& why, @@ -242,18 +334,16 @@ int line) : Exception(why, who, file, line) -// , std::runtime_error(why) -{ -} - -//***************************************************************************** -// RuntimeError::what -//***************************************************************************** -//const char* RuntimeError::what() const throw() -//{ - //return Exception::what(); -//} +{ +} //***************************************************************************** // RangeError::RangeError +//> Allocate memory and instantiate an RangeError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** RangeError::RangeError(const std::string& why, @@ -268,4 +358,8 @@ //***************************************************************************** // RangeError::what +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< //***************************************************************************** const char* RangeError::what() const throw() @@ -276,4 +370,11 @@ //***************************************************************************** // OverflowError::OverflowError +//> Allocate memory and instantiate an OverflowError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** OverflowError::OverflowError(const std::string& why, @@ -288,4 +389,8 @@ //***************************************************************************** // OverflowError::what +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< //***************************************************************************** const char* OverflowError::what() const throw() @@ -296,4 +401,11 @@ //***************************************************************************** // UnderflowError::UnderflowError +//> Allocate memory and instantiate an UnderflowError object with details. +// +// @param why The reason for raising the exception. +// @param who The module to add to the call stack. +// @param file The file containing the module. +// @param line The line number where the exception was encountered. +//< //***************************************************************************** UnderflowError::UnderflowError(const std::string& why, @@ -308,4 +420,8 @@ //***************************************************************************** // UnderflowError::what +//> Provide additional information about the exceptional condition. +// +// @return The detailed error message. +//< //***************************************************************************** const char* UnderflowError::what() const throw() @@ -315,11 +431,2 @@ } - -//***************************************************************************** -// ::operator<< -//***************************************************************************** -//Util_API std::ostream& operator<<(std::ostream& os, -// const Damkjer::Exception& e) -//{ -// return os << e.what(); -//} Index: Damkjer/Util/Exception/Exception.h =================================================================== --- Damkjer/Util/Exception/Exception.h (revision 10) +++ Damkjer/Util/Exception/Exception.h (revision 12) @@ -4,24 +4,30 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: -// -// LIMITATIONS: +// DESCRIPTION: +//> The interface definitions for exception classes that parallel the STL +// exception classes. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: -//> 2012-JUL-27 K. Damkjer +//> 2013-JUL-27 K. Damkjer // Initial Coding. //< //***************************************************************************** -#ifndef Exception_HEADER -#define Exception_HEADER - -#include -#include -#include -#include -#include - -#include "Util/UtilAPI.h" +#ifndef Damkjer_Exception_HEADER +#define Damkjer_Exception_HEADER + +#include // USES typeid operator. +#include // ISA extension to STL exception classes. +#include // ISA extension to STL logic and runtime errors. +#include // HASA std::vector data member. +#include // HASA std::string data member. +#include // USES std::ostream::operator<<. + +#include "Util/UtilAPI.h" // ISA contributor to the Util libraray API. namespace Damkjer @@ -30,22 +36,22 @@ //***************************************************************************** // CLASS: Exception -//> Exception objects allow for detailed, robust handling of errors and -// exceptional circumstances encountered in programs. This class, and its -// derivatives, intnentionally mirror the C++ Standard Library exception -// classes. They also provide for standardized message formatting and stack -// trace aggregation through convenience macros. +//> Abstract base class for exception classes. Exceptions allow for detailed, +// robust handling of errors and exceptional circumstances encountered in +// programs. This class, and its derivatives, intnentionally mirror the C++ +// Standard Library exception classes. They also provide for standardized +// message formatting and stack trace aggregation through convenience macros. // // The implemented exceptions that parallel the C++ Standard Library are: // -//- Exception -> std::exception -//- LogicError -> std::logic_error -//- DomainError -> std::domain_error -//- InvalidArgument -> std::invalid_argument -//- LengthError -> std::length_error -//- OutOfRange -> std::out_of_range -//- RuntimeError -> std::runtime_error -//- RangeError -> std::range_error -//- OverflowError -> std::overflow_error -//- UnderflowError -> std::underflow_error +// - Exception -> std::exception +// - LogicError -> std::logic_error +// - DomainError -> std::domain_error +// - InvalidArgument -> std::invalid_argument +// - LengthError -> std::length_error +// - OutOfRange -> std::out_of_range +// - RuntimeError -> std::runtime_error +// - RangeError -> std::range_error +// - OverflowError -> std::overflow_error +// - UnderflowError -> std::underflow_error //< //***************************************************************************** @@ -53,24 +59,33 @@ { public: - Util_API virtual ~Exception() throw(); - //> - //< + // Use the compiler-generated default constructor. + // Util_API Exception(); + + // Use the compiler-generated copy constructor. + // Util_API Exception(const Exception&); + + Util_API virtual ~Exception() throw(){} + //> Destroy the Exception object and perform clean-up activities. + //< + + // Use the compiler-generated assignment operator. + // Util_API Exception& operator=(const Exception&); Util_API virtual const char* what() const throw() = 0; - //> + //> Provide additional information about the exceptional condition. //< Util_API virtual std::ostream& message(std::ostream&) const; - //> + //> Apply standard formatting to the exception verbose message stream. //< Util_API void push(const std::string&, - const std::string&, - const int) const; - //> + const std::string&, + const int) const; + //> Add a record to the exception stack trace. //< Util_API std::ostream& stackTrace(std::ostream&) const; - //> + //> Provide a stack trace for the exceptional condition. //< @@ -82,55 +97,99 @@ return theTypeID; } + //> Provide the type of the exception class. + // + // @return The type of the exception class. + //< + Util_API const std::string& why() const { return theWhy; } + //> Provide additional information about the cause of the exceptional + // condition, if possible. + // + // @return The verbose description for the cause of the exception. + //< + Util_API const std::string& who() const { return theWho; } + //> Identify the module that raised the exception. + // + // @return The module that raised the exception + //< + Util_API const std::string& file() const { return theFile; } - Util_API const int line() const { return theLine; } + //> Identify the file containing the code emitting the exception. + // + // @return The file containing the code emitting the exception. + //< + + Util_API const int line() const { return theLine; } + //> Identify the line number of the originating location for the + // exception. + // + // @return The line number for the exception origin. + //< protected: Util_API Exception(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an Exception object with details. //< Util_API virtual std::ostream& insertReason(std::ostream&) const; - //> + //> Insert the reason for raising the exception into the output stream. //< private: + mutable std::vector theStack; + //> The call stack. + //< + mutable std::string theTypeID; + //> The exception type. + //< + + mutable std::string theMsg; + //> The verbose message. + //< + std::string theWhy; + //> The reason for raising the exception. + //< + std::string theWho; + //> The originator of the exception. + //< + std::string theFile; - int theLine; - - mutable std::string theMsg; - - mutable std::vector theStack; + //> The file containing the exception throw site. + //< + + int theLine; + //> The location of the exception throw. + //< }; //***************************************************************************** // CLASS: LogicError -//> -//< -//***************************************************************************** -class LogicError : public Exception//, -// public std::logic_error +//> An error raised due to faulty logic. +// +// Logic errors are errors that, at least in theory, could be avoided by the +// program; for example, by performing additional tests of function +// arguments. Examples of such errors are a violation of logical +// preconditions or a class invariant under the Design-by-Contract idiom. +//< +//***************************************************************************** +class LogicError : public Exception { public: Util_API LogicError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an LogicError object with details. //< Util_API virtual ~LogicError() throw() {} - //> - //< - -// Util_API virtual const char* what() const throw(); - //> + //> Destroy the LogicError object and perform clean-up activities. //< }; @@ -138,5 +197,10 @@ //***************************************************************************** // CLASS: DomainError -//> +//> An error raised due to an operation being undefined for an argument. +// +// A domain error typically applies to mathematic functions where the domain +// is the subset of values that can be accepted by the function. In this +// case, an argument encountered outside of the valid subset of values is a +// domain error. //< //***************************************************************************** @@ -146,16 +210,16 @@ public: Util_API DomainError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an DomainError object with details. //< Util_API virtual ~DomainError() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the DomainError object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -163,24 +227,28 @@ //***************************************************************************** // CLASS: InvalidArgument -//> +//> An error raised due to an argument being rejected as valid input. +// +// An invalid argument is a general class of exception that reflects a +// violation of logical preconditions for a function. //< //***************************************************************************** class InvalidArgument : public LogicError, - public std::invalid_argument + public std::invalid_argument { public: Util_API InvalidArgument(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an InvalidArgument object with + // details. //< Util_API virtual ~InvalidArgument() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the InvalidArgument object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -188,24 +256,25 @@ //***************************************************************************** // CLASS: LengthError -//> +//> An error raised due to an attempt to perform an action that would exceed +// implementation defined length limits for an object. //< //***************************************************************************** class LengthError : public LogicError, - public std::length_error + public std::length_error { public: Util_API LengthError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an LengthError object with details. //< Util_API virtual ~LengthError() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the LengthError object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -213,24 +282,28 @@ //***************************************************************************** // CLASS: OutOfRange -//> +//> An error raised due to an attempt to access elements outside of a defined +// range. +// +// A typical example of an out of range error is an invalid index for a +// container element. //< //***************************************************************************** class OutOfRange : public LogicError, - public std::out_of_range + public std::out_of_range { public: Util_API OutOfRange(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an OutOfRange object with details. //< Util_API virtual ~OutOfRange() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the OutOfRange object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -238,5 +311,9 @@ //***************************************************************************** // CLASS: RethrowError -//> +//> An error raised due to an unhandled exception thrown within a guarded +// section. +// +// Rethrow errors are used to capture the call trace between an exception +// origin and its handling location. //< //***************************************************************************** @@ -245,18 +322,15 @@ public: Util_API RethrowError(const std::exception&, - const std::string&, - const std::string&, - int); - //> This constructor is used to wrap a std::exception as a - // Damkjer::Exception for the purpose of rethrowing. The what() - // portion of the std::exception is reported in the what() - // of the RethrowError. + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an RethrowError object with details. //< Util_API RethrowError(const Damkjer::Exception& thrown, - const std::string& extraReason, - const std::string& who, - const std::string& file, - int line) + const std::string& extraReason, + const std::string& who, + const std::string& file, + int line) : DomainError(thrown.why() + " " + extraReason, who, file, line) { @@ -264,10 +338,17 @@ //> This constructor is used to add an extra reason to a // Damkjer::Exception for the purpose of rethrowing. + // + // @param thrown The original thrown exception to be re-thrown. + // @param extraReason The additional reason for re-throwing. + // @param who The module to add to the call stack. + // @param file The file containing the module. + // @param line The line number where the exception was + // encountered. //< Util_API RethrowError(const std::string& why, - const std::string& who, - const std::string& file, - int line) + const std::string& who, + const std::string& file, + int line) : DomainError(why, who, file, line) { @@ -277,9 +358,14 @@ // portion of the std::exception is reported in the what() // of the RethrowError. + // + // @param why The reason for raising the exception. + // @param who The module to add to the call stack. + // @param file The file containing the module. + // @param line The line number where the exception was encountered. //< Util_API RethrowError(const std::string& who, - const std::string& file, - int line) + const std::string& file, + int line) : DomainError("Unknown error", who, file, line) { @@ -288,4 +374,12 @@ // Damkjer::Exception for the purpose of rethrowing. The message // "Unknown error" is reported in the what() of the RethrowError. + // + // @param who The module to add to the call stack. + // @param file The file containing the module. + // @param line The line number where the exception was encountered. + //< + + Util_API virtual ~RethrowError() throw() {} + //> Destroy the RethrowError object and perform clean-up activities. //< }; @@ -293,24 +387,22 @@ //***************************************************************************** // CLASS: RuntimeError -//> -//< -//***************************************************************************** -class RuntimeError : public Exception//, -// public std::runtime_error +//> An error raised due to events beyond the scope of the program and only +// detectable at run-time. +// +// Runtime errors are errors that are not easily avoided by the program. +//< +//***************************************************************************** +class RuntimeError : public Exception { public: Util_API RuntimeError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an RuntimeError object with details. //< Util_API virtual ~RuntimeError() throw() {} - //> - //< - -// Util_API virtual const char* what() const throw(); - //> + //> Destroy the RuntimeError object and perform clean-up activities. //< }; @@ -318,24 +410,31 @@ //***************************************************************************** // CLASS: RangeError -//> +//> An error raised due to a defined, but unrepresentable result. +// +// Range errors are typically used to report a floating-point value that +// would be too large or small in magnitude to represent. +// +// @note +// Do not use this class to report out of range logical errors. For example, +// an index out of bounds would not be a range error. //< //***************************************************************************** class RangeError : public RuntimeError, - public std::range_error + public std::range_error { public: Util_API RangeError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an RangeError object with details. //< Util_API virtual ~RangeError() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the RangeError object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -343,24 +442,28 @@ //***************************************************************************** // CLASS: OverflowError -//> +//> An error raised due to a value growing too large resulting in an +// arithmetic overflow. +// +// Overflow errors are tpically used to report an integer computation that +// would exceed the maximum representable value for the integer class. //< //***************************************************************************** class OverflowError : public RuntimeError, - public std::overflow_error + public std::overflow_error { public: Util_API OverflowError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an OverflowError object with details. //< Util_API virtual ~OverflowError() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the OverflowError object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -368,24 +471,29 @@ //***************************************************************************** // CLASS: UnderflowError -//> +//> An error raised due to a value growing too small resulting in an +// arithmetic underflow. +// +// Underflow errors are tpically used to report an integer computation that +// would exceed the minimum representable value for the integer class. //< //***************************************************************************** class UnderflowError : public RuntimeError, - public std::underflow_error + public std::underflow_error { public: Util_API UnderflowError(const std::string&, - const std::string&, - const std::string&, - int); - //> + const std::string&, + const std::string&, + int); + //> Allocate memory and instantiate an UnderflowError object with + // details. //< Util_API virtual ~UnderflowError() throw() {} - //> - //< - - Util_API virtual const char* what() const throw(); - //> + //> Destroy the UnderflowError object and perform clean-up activities. + //< + + Util_API virtual const char* what() const throw(); + //> Provide additional information about the exceptional condition. //< }; @@ -393,6 +501,16 @@ } -Util_API inline std::ostream& operator<<(std::ostream& os, - const Damkjer::Exception& e) +//***************************************************************************** +// FUNCTION: operator<<(std::ostream&, const Damkjer::Exception&) +//> Insert a human-readable summary of the Damkjer::Exception into the output +// stream. +// +// @param os The output stream to accept the error message. +// @param e The Damkjer::Exception object to provide the error message. +// @return The updated output stream. +//< +//***************************************************************************** +Util_API inline std::ostream& +operator<<(std::ostream& os, const Damkjer::Exception& e) { return os << e.what(); @@ -401,8 +519,12 @@ //***************************************************************************** // MACRO: EXCEPTION_TRY -//> -//< -//***************************************************************************** -#define EXCEPTION_TRY(MODULE_NAME) \ +//> Establish a guarded section for a module. The module name will be +// appended to the stack trace for any unhandled exceptions. This macro +// should be at the beginning of any module that may throw an exception. +// +// @param MODULE_NAME The module identifier (and signature). +//< +//***************************************************************************** +#define EXCEPTION_TRY( MODULE_NAME ) \ static const char* const MODULE = MODULE_NAME; \ try \ @@ -411,5 +533,7 @@ //***************************************************************************** // MACRO: EXCEPTION_RETHROW -//> +//> Intercept unhandled exceptions and append the current module to the stack +// trace. This macro should be placed at the end of any module where an +// unhandled exception may be encountered. //< //***************************************************************************** @@ -432,5 +556,9 @@ //***************************************************************************** // MACRO: EXCEPTION_CATCHALL -//> +//> Intercept exceptions immediately prior to throwing off the stack. Instead +// of a hard crash, provide any exception messages and any stack trace +// information available. Always return with a failure code to indicate +// unsucessful program execution. This macro should be placed at the end of +// all application main functions. //< //***************************************************************************** Index: Damkjer/Util/Exception/test/TestException.cpp =================================================================== --- Damkjer/Util/Exception/test/TestException.cpp (revision 10) +++ Damkjer/Util/Exception/test/TestException.cpp (revision 12) @@ -21,5 +21,5 @@ #include -#include "damkjerConfig.h" +#include "Util/Exception/Exception.h" #include "TestException.h" #include "Util/Streams/BlockIndent.h" @@ -59,5 +59,5 @@ { test.report() << "Caught expected exception:\n"; - test.report() << blockIndent() << e.what() << "\n" << endBlock; + test.report() << BlockIndent() << e.what() << "\n" << endBlock; // If we get here, we threw the correct exception: successful test. @@ -131,12 +131,18 @@ std::underflow_error sue("Detected arithmetic underflow. (result is " "smaller than type can represent)"); - std::bad_alloc sba("Unable to allocate requested memory."); - std::bad_cast sbc("Failure to dynamic cast. Cast relationship is " - "defined, but results in an incomplete object of" - "the destination type"); - std::bad_exception sbe("Exception thrown that wasn't listed in the " - "function dynamic exception specifier."); - std::bad_typeid sbt("typeid operator applied to dereferenced null " - "pointer."); + +// std::bad_alloc sba("Unable to allocate requested memory."); +// std::bad_cast sbc("Failure to dynamic cast. Cast relationship is " +// "defined, but results in an incomplete object of" +// "the destination type"); +// std::bad_exception sbe("Exception thrown that wasn't listed in the " +// "function dynamic exception specifier."); +// std::bad_typeid sbt("typeid operator applied to dereferenced null " +// "pointer."); + + std::bad_alloc sba; + std::bad_cast sbc; + std::bad_exception sbe; + std::bad_typeid sbt; registerStep(new throwTest(sde)); Index: Damkjer/Util/Exception/test/TestException.h =================================================================== --- Damkjer/Util/Exception/test/TestException.h (revision 9) +++ Damkjer/Util/Exception/test/TestException.h (revision 12) @@ -29,4 +29,7 @@ //> //< +private: + TestException(const TestException&); + TestException& operator=(const TestException&); }; Index: Damkjer/Util/Exception/test/TestException.vcxproj =================================================================== --- Damkjer/Util/Exception/test/TestException.vcxproj (revision 10) +++ Damkjer/Util/Exception/test/TestException.vcxproj (revision 12) @@ -2,4 +2,12 @@ + + DebugOMP + Win32 + + + DebugOMP + x64 + Debug @@ -26,9 +34,4 @@ x64 - - - - {20fe2624-c64f-d61a-bd8f-1725a8e68a42} - @@ -39,4 +42,9 @@ + + + {20fe2624-c64f-d61a-bd8f-1725a8e68a42} + + Win32Proj @@ -48,5 +56,13 @@ true + + Application + true + + Application + true + + Application true @@ -74,5 +90,11 @@ + + + + + + @@ -94,5 +116,13 @@ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ @@ -130,4 +160,25 @@ + + + + + + + _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + Console + + setlocal @@ -171,4 +222,24 @@ + + + + + + + _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + Console + + setlocal @@ -247,4 +318,7 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) true + AnySuitable + true + Speed @@ -333,4 +407,8 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) true + /wd4514 /wd4571 /wd4668 /wd4710 /wd4711 /wd4820 /wd4986 %(AdditionalOptions) + AnySuitable + true + Speed Index: Damkjer/Util/Exception/test/test_Exception.cpp =================================================================== --- Damkjer/Util/Exception/test/test_Exception.cpp (revision 9) +++ Damkjer/Util/Exception/test/test_Exception.cpp (revision 12) @@ -14,5 +14,5 @@ //***************************************************************************** -#include "damkjerConfig.h" +#include "Util/Exception/Exception.h" #include "TestException.h" Index: Damkjer/Util/FileIO/GeoKey/ProjLinearUnitsGeoKey.m =================================================================== --- Damkjer/Util/FileIO/GeoKey/ProjLinearUnitsGeoKey.m (revision 0) +++ Damkjer/Util/FileIO/GeoKey/ProjLinearUnitsGeoKey.m (revision 12) @@ -1,62 +1,174 @@ +% ProjLinearUnitsGeoKey Vantage Point Tree spatial indexing data structure +% +% File: ProjLinearUnitsGeoKey.m +% +% Description: +% Provides the definition for GeoTIFF Projected Linear Units Keys. +% +% Limitations: +% No known limitations. +% +% Properties: +% code - The code for the projected linear unit described by this +% key. +% interpretation - The interpretation of the projected linear unit described +% by this key. +% +% Methods: +% [this] = ProjLinearUnitsGeoKey(varargin) - Constructor +% +% Toolbox requirements: +% None. +% +% Script requirements: +% None. +% +% Data requirements: +% None. +% +% References: +% http://www.remotesensing.org/geotiff/spec/geotiffhome.html +% +% See Also: +% None. +% + +% Copyright (C) 2012 Kristian L. Damkjer. +% +% Software History: +% 2012-SEP-07 K. Damkjer +% Initial Coding. +% + +%****************************************************************************** +% CLASS: ProjLinearUnitsGeoKey +% GeoTIFF Projected Linear Units Key. There are several different kinds of +% units that may be used in geographically related raster data: linear +% units, angular units, units of time (e.g. for radar-return), CCD-voltages, +% etc. For this reason there will be a single, unique range for each kind of +% unit, broken down into the following currently defined ranges: +% +% Range | Allocation +% ---------------|-------------------------------------------------------- +% 0 | undefined +% [ 1, 2000] | Obsolete GeoTIFF codes +% [2001, 8999] | Reserved by GeoTIFF +% [9000, 9099] | EPSG Linear Units. +% [9100, 9199] | EPSG Angular Units. +% 32767 | user-defined unit +% [32768, 65535] | Private User Implementations +% +% Linear Unit Values (See the ESPG/POSC tables for definition): +% Unit | Code +% ----------------------------|------------------------------------------ +% Meter | 9001 +% Foot | 9002 +% Foot (US Survey) | 9003 +% Foot (Modified American) | 9004 +% Foot (Clarke) | 9005 +% Foot (Indian) | 9006 +% Link | 9007 +% Link (Benoit) | 9008 +% Link (Sears) | 9009 +% Chain (Benoit | 9010 +% Chain (Sears) | 9011 +% Yard (Sears) | 9012 +% Yard (Indian) | 9013 +% Fathom | 9014 +% International Nautical Mile | 9015 +%****************************************************************************** classdef (Sealed = true) ProjLinearUnitsGeoKey < GeoKey - properties - code = 2 - end - - properties (GetAccess = private,Constant = true) - codes = containers.Map(... - {9001,... - 9002,... - 9003,... - 9004,... - 9005,... - 9006,... - 9007,... - 9008,... - 9009,... - 9010,... - 9011,... - 9012,... - 9013,... - 9014,... - 9015},... - {'Meter',... - 'Foot',... - 'Foot (US Survey)',... - 'Foot (Modified American)',... - 'Foot (Clarke)',... - 'Foot (Indian)',... - 'Link',... - 'Link (Benoit)',... - 'Link (Sears)',... - 'Chain (Benoit)',... - 'Chain (Sears)',... - 'Yard (Sears)',... - 'Yard (Indian)',... - 'Fathom',... - 'International Nautical Mile'}); - end - - properties (Dependent) - interpretation - end - - methods - function vlr = ProjLinearUnitsGeoKey(varargin) - if (nargin == 1) - if (~vlr.codes.isKey(varargin{1})) - error('ProjLinearUnitsGeoKey:InitError',... - 'Unknown Unit'); - end - vlr.code = varargin{1}; + properties + % The code for the projected linear unit described by this key. The + % default value, 0, indicates "undefined". + code = 0 + end + + properties (Access = private, Constant = true) + % The mapping of defined codes and interpretations. + codes = containers.Map(... + {9001,... + 9002,... + 9003,... + 9004,... + 9005,... + 9006,... + 9007,... + 9008,... + 9009,... + 9010,... + 9011,... + 9012,... + 9013,... + 9014,... + 9015},... + {'Meter',... + 'Foot',... + 'Foot (US Survey)',... + 'Foot (Modified American)',... + 'Foot (Clarke)',... + 'Foot (Indian)',... + 'Link',... + 'Link (Benoit)',... + 'Link (Sears)',... + 'Chain (Benoit)',... + 'Chain (Sears)',... + 'Yard (Sears)',... + 'Yard (Indian)',... + 'Fathom',... + 'International Nautical Mile'}); + end + + properties (Dependent) + % The interpretation of the projected linear unit described by this key. + interpretation + end + + methods + %************************************************************************ + % ProjLinearUnitsGeoKey/ProjLinearUnitsGeoKey + %************************************************************************ + function this = ProjLinearUnitsGeoKey(varargin) + % The Constructor. The constructor may be called with an argument + % list to specify the code for the key. If no argument is provided, + % the default constructor creates a key with "undefined" linear unit. + % + % Parameters: + % varargin - Variable-length input argument list. The argument list + % may contain up to a single argument. If an argument is + % provided, it will be checked against the list of known + % linear units. if the code is not recognized, an error + % will be thrown. Similarly, if the constructor is + % called with more than one argument, an error will be + % thrown. + + if (nargin == 0) + this.code = 0; + elseif (nargin == 1) + if (~this.codes.isKey(varargin{1})) + error('ProjLinearUnitsGeoKey:InitError',... + 'Unknown Unit'); end - end - - function meaning = get.interpretation(vlr) - % Required accessor for dependent property: interpretation - - meaning = vlr.codes(vlr.code); - end - - end + this.code = varargin{1}; + elseif (nargin > 1) + error('ProjLinearUnitsGeoKey:InvalidArgument',... + 'Too many arguments provided to constructor.'); + end + end + + %************************************************************************ + % ProjLinearUnitsGeoKey/get.interpretation + %************************************************************************ + function meaning = get.interpretation(this) + % Reinterpret the key code in human-readable format. + % + % Returns: + % meaning - The interpretation of the code. + + meaning = this.codes(this.code); + end + + end end + + Index: Damkjer/Util/FileIO/LasFile/LasFile.m =================================================================== --- Damkjer/Util/FileIO/LasFile/LasFile.m (revision 7) +++ Damkjer/Util/FileIO/LasFile/LasFile.m (revision 12) @@ -64,4 +64,8 @@ % +%****************************************************************************** +% CLASS: LasFile +% An ASPRS LAS version 1.2 file structure. +%****************************************************************************** classdef (Sealed = true) LasFile properties @@ -130,20 +134,20 @@ % operations. % - % Value | Meaning - % ------+---------------------------------------------------------- - % 0 | Created, never classified - % 1 | Unclassified - % 2 | Ground - % 3 | Low Vegetation - % 4 | Medium Vegetation - % 5 | High Vegetation - % 6 | Building - % 7 | Low Point (noise) - % 8 | Model Key-point (mass point) - % 9 | Water - % 10 | Reserved for ASPRS Definition - % 11 | Reserved for ASPRS Definition - % 12 | Overlap Point - % 13-31 | Reserved for ASPRS Definition + % | Value | Meaning | + % |-------|----------------------------------------------------------| + % | 0 | Created, never classified | + % | 1 | Unclassified | + % | 2 | Ground | + % | 3 | Low Vegetation | + % | 4 | Medium Vegetation | + % | 5 | High Vegetation | + % | 6 | Building | + % | 7 | Low Point (noise) | + % | 8 | Model Key-point (mass point) | + % | 9 | Water | + % | 10 | Reserved for ASPRS Definition | + % | 11 | Reserved for ASPRS Definition | + % | 12 | Overlap Point | + % | 13-31 | Reserved for ASPRS Definition | classification @@ -218,7 +222,7 @@ % The Point Color % - % Red : The Red image channel value associated with this point - % Green: The Green image channel value associated with this point - % Blue : The Blue imagechannel value associated with this point + % Red - The Red image channel value associated with this point + % Green - The Green image channel value associated with this point + % Blue - The Blue imagechannel value associated with this point pColor end @@ -244,11 +248,14 @@ % The Point Color % - % Red : The Red image channel value associated with this point - % Green: The Green image channel value associated with this point - % Blue : The Blue imagechannel value associated with this point + % Red - The Red image channel value associated with this point + % Green - The Green image channel value associated with this point + % Blue - The Blue imagechannel value associated with this point color end methods + %************************************************************************ + % LasFile/LasFile + %************************************************************************ function lasFile = LasFile(varargin) % Constructor for LasFile objects @@ -277,21 +284,49 @@ end + %************************************************************************ + % LasFile/get.points + %************************************************************************ function pointData = get.points(lasFile) % Required accessor for dependent property: points + % + % Returns: + % pointData - The point set data for this LAS file object. pointData = lasFile.pPoints; end + %************************************************************************ + % LasFile/get.gpsTime + %************************************************************************ function timeData = get.gpsTime(lasFile) % Required accessor for dependent property: gpsTime + % + % Returns: + % timeData - The GPS time data for this LAS file object. timeData = lasFile.pGpsTime; end + %************************************************************************ + % LasFile/get.color + %************************************************************************ function colorData = get.color(lasFile) % Required accessor for dependent property: color + % + % Returns: + % colorData - The color data for this LAS file object. colorData = lasFile.pColor; end + %************************************************************************ + % LasFile/set.points + %************************************************************************ function lasFile = set.points(lasFile, pointData) % Controlled interface for setting point data on LasFile objects + % + % Parameters: + % pointData - The point set data to add to this LAS object. + % + % Returns: + % lasFile - The LAS file object with updated point data. + if (size(pointData,1) ~= 3) error('LasFile:DimensionMismatch',... @@ -369,6 +404,16 @@ end + %************************************************************************ + % LasFile/set.gpsTime + %************************************************************************ function lasFile = set.gpsTime(lasFile, timeData) % Controlled interface for setting GPS time data on LasFile objects + % + % Parameters: + % timeData - The GPS time information to add to this LAS object's + % point set. + % + % Returns: + % lasFile - The LAS file object with updated GPS time data. if (size(timeData,2) ~= lasFile.publicHeader.nPoints) @@ -389,8 +434,18 @@ end + %************************************************************************ + % LasFile/set.color + %************************************************************************ function lasFile = set.color(lasFile, colorData) % Controlled interface for setting color data on LasFile objects. - - if (~strcmp(class(colorData),'uint16')) + % + % Parameters: + % colorData - The color information to add to this LAS object's + % point set. + % + % Returns: + % lasFile - The LAS file object with updated color data. + + if (~isa(colorData,'uint16')) error('LasFile:DataTypeMismatch',... 'Color data must be of type uint16'); @@ -419,6 +474,17 @@ end + %************************************************************************ + % LasFile/loadFrom + %************************************************************************ function lasFile = loadFrom(lasFile,location) % Load the LAS file from the given location. + % + % Parameters: + % location - The file name or handle containing LAS data to load + % into this object. + % + % Returns: + % lasFile - The LAS file object with data populated from the input + % file location. if (ischar(location)) @@ -542,6 +608,13 @@ end + %************************************************************************ + % LasFile/saveTo + %************************************************************************ function saveTo(lasFile,location) % Save the LAS file to the given location. + % + % Parameters: + % location - The file name or handle to receive this object's + % state. if (ischar(location)) Index: Damkjer/Util/FileIO/LasFile/LasPublicHeader.m =================================================================== --- Damkjer/Util/FileIO/LasFile/LasPublicHeader.m (revision 7) +++ Damkjer/Util/FileIO/LasFile/LasPublicHeader.m (revision 12) @@ -77,6 +77,10 @@ % +%****************************************************************************** +% CLASS: LasPublicHeader +% An ASPRS LAS version 1.2 file public header block. +%****************************************************************************** classdef (Sealed = true) LasPublicHeader - properties (SetAccess = private) + properties (Constant) % The File Signature % @@ -109,16 +113,16 @@ % % Bits | Field Name | Description - % -----+---------------+----------------------------------------- - % 0 | GPS Time Type | The meaning of GPS Time in the Point - % | | Records - % | | 0(not set) -> GPS Time in the point - % | | record fields is GPS Week Time (the same - % | | as previous versions of LAS) - % | | 1 (set) -> GPS Time is standard GPS Time - % | | (satellite GPS Time) minus 1 x 10^9. The - % | | offset moves the time back to near zero - % | | to improve floating point resolution. - % -----+---------------+----------------------------------------- + % -----|---------------|----------------------------------------------- + % 0 | GPS Time Type | The meaning of GPS Time in the Point Records % 1:15 | Reserved | Must be set to zero. + % + % The GPS Time Type bit carries the following interpretations: + % + % Value | Description + % ------------|-------------------------------------------------------- + % 0 (not set) | GPS Week Time (the same as previous versions of LAS) + % 1 (set) | Standard GPS Time (satellite GPS Time) minus 1e9.* + % * The offset moves the time back to near zero to improve floating + % point resolution. globalEncoding = uint16(0) @@ -184,21 +188,11 @@ % % Generating Agent | System ID - % ---------------------------------------+----------------------- - % Hardware System | String identifying - % | hardware (e.g. "ALTM - % | 1210" or "ALS50" - % ---------------------------------------+----------------------- + % ---------------------------------------|----------------------- + % Hardware System | String identifying hardware (e.g., "ALTM 1210" or "ALS50") % Merge of one or more files | "MERGE" - % ---------------------------------------+----------------------- % Modification of a single file | "MODIFICATION" - % ---------------------------------------+----------------------- % Extraction from one or more files | "EXTRACTION" - % ---------------------------------------+----------------------- % Reprojection, rescaling, warping, etc. | "TRANSFORMATION" - % ---------------------------------------+----------------------- - % Some other operation | "OTHER" or a string up - % | to 32 characters - % | identifying the - % | operation + % Some other operation | "OTHER" or a string up to 32 characters identifying the operation systemIdentifier = 'OTHER' @@ -415,5 +409,5 @@ end - properties (Dependent) + properties (Dependent, SetAccess = private) % The File Creation Date % @@ -446,4 +440,7 @@ methods + %************************************************************************ + % LasPublicHeader/LasPublicHeader + %************************************************************************ function header = LasPublicHeader(varargin) % Constructor for LasFile public header block objects @@ -465,9 +462,24 @@ end + %************************************************************************ + % LasPublicHeader/get.fileCreationDate + %************************************************************************ function theDate = get.fileCreationDate(header) + % The File Creation Date + % + % The date on which the file was created expressed as a date + % string. theDate = datestr(header.pFileCreationDate); end + %************************************************************************ + % LasPublicHeader/get.fileCreationDayOfYear + %************************************************************************ function theDOY = get.fileCreationDayOfYear(header) + % The File Creation Day of Year + % + % The day, expressed as an unsigned short, on which this file was + % created. Day is computed as the Greenwhich Mean Time (GMT) day. + % January 1 is considered day 1. theDOY = header.pFileCreationDate-... datenum(... @@ -476,5 +488,12 @@ end + %************************************************************************ + % LasPublicHeader/get.fileCreationYear + %************************************************************************ function theYear = get.fileCreationYear(header) + % The File Creation Year + % + % The year, expressed as a four digit number, in which the file was + % created. theYear = uint16(... str2double(... @@ -482,9 +501,22 @@ end + %************************************************************************ + % LasPublicHeader/get.version + %************************************************************************ function theVersion = get.version(header) + % The Version Number + % + % The version number consists of a major and minor field. The major + % and minor fields combine to form the number that indicates the + % format number of the current specification itself. For example, + % specification number 1.2 (this version) would contain 1 in the + % major field and 2 in the minor field. theVersion = [num2str(header.pVersionMajor) '.'... num2str(header.pVersionMinor)]; end + %************************************************************************ + % LasPublicHeader/loadFrom + %************************************************************************ function header = loadFrom(header, location) % Load the LAS file public header from the given location. @@ -559,4 +591,7 @@ end + %************************************************************************ + % LasPublicHeader/saveTo + %************************************************************************ function saveTo(header, location) % Save the LAS file public header to the given location. Index: Damkjer/Util/FileIO/LasFile/LasVlrOld.m =================================================================== --- Damkjer/Util/FileIO/LasFile/LasVlrOld.m (revision 6) +++ Damkjer/Util/FileIO/LasFile/LasVlrOld.m (revision 12) @@ -15,5 +15,5 @@ % % Methods: -% [vlr] = loadFrom(location) - Load LAS VLR from a gicen location. +% [vlr] = loadFrom(location) - Load LAS VLR from a given location. % saveTo(location) - Save LAS VLR to a given location. % Index: Damkjer/Util/MATLAB/ClassHandle.h =================================================================== --- Damkjer/Util/MATLAB/ClassHandle.h (revision 9) +++ Damkjer/Util/MATLAB/ClassHandle.h (revision 12) @@ -4,34 +4,29 @@ // Copyright (C) 2012 Kristian L. Damkjer. // -// DESCRIPTION: This class is intended to be used to wrap C++ objects for -// transport across mex function calls in MATLAB. -// -// LIMITATIONS: To preserve the lifetime guarantees of the pointer, default -// construction, copy construction and assignment are -// explicitly disallowed. -// -// The class handle owns the pointer it contains. Thus, when -// the class handle is destroyed, the pointer is deleted. -// -// Class handles are forced to be allocated on the heap by -// using the named constructor idiom. Class handles should be -// destroyed using the destroyHandleTo template function. +// DESCRIPTION: +//> The interface definition for C++ class handle objects. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: //> 2012-OCT-08 K. Damkjer // Initial Coding. -//> 2013-JUN-24 K. Damkjer +// 2013-JUN-24 K. Damkjer // Clarified Error ID. //< //***************************************************************************** -#ifndef ClassHandle_HEADER -#define ClassHandle_HEADER - -#include - -#include "damkjerConfig.h" - +#ifndef Damkjer_ClassHandle_HEADER +#define Damkjer_ClassHandle_HEADER + +#include // USES the typeid operator +#include // HASA std::string data member + +//*** // Fix "wide char" definition for older versions of MATLAB. This must be placed -// after other includes and before the mex.h include. +// after other includes and before the MathWorks includes. +//*** #if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) @@ -40,133 +35,170 @@ #endif -#include "matrix.h" +#include // USES MathWorks types +#include "matrix.h" // HASA mxArray interface, USES matrix interfaces +#include "mex.h" // USES MEX error interfaces, mexLock and mexUnlock namespace Damkjer { //***************************************************************************** -// FUNCTION: ptrAsMat -//***************************************************************************** -template -mxArray* ptrAsMat(BASE*); -//> This function reinterprets the pointer to the base object as a MEX index -// and encapsulates the result in a MATLAB matrix object to persist between -// MEX function calls. -//< - -//***************************************************************************** // CLASS: ClassHandle -//***************************************************************************** -template +//> A C++ object wrapper to enable object persistence across MEX function +// calls in MATLAB. +// +// This class implements an encapsulation scheme to wrap an object in a +// generic handle container that's allocated on the heap. This container is +// then reinterpreted as a MATLAB memory-managed matrix for safe transport +// between MEX function calls. The general scheme was developed through +// collaboration on the MathWorks forums: +// +// http://www.mathworks.com/matlabcentral/newsreader/view_thread/278243 +// +// @note +// Default construction, copy construction and assignment are explicitly +// disallowed to preserve the lifetime guarantees of the pointer. +// ClassHandle owns the pointer it contains. Thus, when the ClassHandle is +// destroyed, the pointer is deleted to free the resources for the wrapped +// object. ClassHandle objects are encouraged to be allocated on the heap +// via ClassHandle::createHandle by using the named constructor idiom. From +// a MEX source file, the ClassHandle objects should be destroyed using the +// ClassHandle::destroyHandle method. +// +// @tparam ObjectT The wrapped object type. +//< +//***************************************************************************** +template class ClassHandle { public: ~ClassHandle(); - //> The destructor. This method is also responsible for invoking mexUnock to - // allow calling MEX files to be cleared after memory management tasks have - // completed. - //< + //> Destroy the ClassHandle object and perform clean-up activities. + //< - const BASE& obj() const { return *thePointer; } - //> This method returns the object encapsulated by the ClassWrapper. - //< + const ObjectT& object() const { return *thePointer; } + //> Return the object encapsulated by the ClassHandle. + // + // @tparam ObjectT The wrapped object type. + // @return A reference to the base class object. + //< bool isValid() const; - //> This method returns true if and only if the ClassHandle object passes - // validity checks. This method prevents the arbitrary reinterpretation of - // non-ClassWrapper objects. - //< - - friend mxArray* ptrAsMat(BASE*); + //> Perform a validity check on the ClassHandle object. + //< + + static mxArray* createHandle(ObjectT*); + //> Create a MathWorks index handle to the argument. + //< + + static const ObjectT& handleReference(const mxArray*); + //> Reinterpret a MathWorks index as a C++ object reference. + //< + + static void destroyHandle(const mxArray*); + //> Free resources for the handle object represented by the MathWorks + // index. + //< private: - ClassHandle(BASE*); - //> We want to force objects to be created using the ptrAsMat named - // constructor idiom. This also forces ClassHandles to be allocated on - // the heap instead of on the stack. This method is responsible for - // invoking mexLock to prevent MATLAB from arbitrarily clearing memory - // managed by the wrapper. - //< - - // Explicitly disable "default" constructors. + +// typedef typename ClassHandle HandleT; + typedef ClassHandle HandleT; + //> Shortcut reference to this class type. + //< + ClassHandle(); - ClassHandle(const ClassHandle&); - ClassHandle& operator=(const ClassHandle&); - - BASE* thePointer; - //> The pointer to the encapsulated object. - //< + //> Explicitly disable the compiler-generated default constructor. No + // definition provided. + //< + + ClassHandle(const ClassHandle&); + //> Explicitly disable the compiler-generated copy constructor. No + // definition provided. + //< + + ClassHandle& operator=(const ClassHandle&); + //> Explicitly disable the compiler-generated assignment operator. No + // definition provided. + // + // @return The updated left-hand side when not disabled. + //< + + ClassHandle(ObjectT*); + //> Initialize a ClassHandle with a pointer to an ObjectT object. + //< + + ObjectT* thePointer; + //> The pointer to the encapsulated object. + //< - std::string theName; - //> The type ID of the base type. Used for validation. - //< - - uint32_T theSignature; - //> The file signature. Used for validation. - //< + std::string theSignature; + //> The file signature. Used for validation. + //< }; //***************************************************************************** -// FUNCTION: ptrAsMat -//***************************************************************************** -template -mxArray* ptrAsMat(BASE* ptr) -{ - mxArray* mat = mxCreateNumericMatrix(1, 1, mxINDEX_CLASS, mxREAL); - *((mwIndex*)mxGetData(mat)) = - reinterpret_cast(new ClassHandle(ptr)); - return mat; -} - -//***************************************************************************** -// FUNCTION: matAsObj -//***************************************************************************** -template -const BASE& matAsObj(const mxArray* mat) -{ - if (mxGetNumberOfElements(mat) != 1 || - mxGetClassID(mat) != mxINDEX_CLASS || - mxIsComplex(mat)) - { - mexErrMsgIdAndTxt("Damkjer:matAsObj:invalidHandle", - "Input must be real-valued index-class scalar."); - } - - ClassHandle* handle = - reinterpret_cast*>(*((mwIndex*)mxGetData(mat))); - - if (!(handle->isValid())) - { - mexErrMsgIdAndTxt("Damkjer:matAsObj:invalidHandle", - "Handle not valid."); - } - - return handle->obj(); -} - -//***************************************************************************** -// FUNCTION: destroyHandleTo -//***************************************************************************** -template -void destroyHandleTo(const mxArray* mat) -{ - if (mxGetNumberOfElements(mat) != 1 || - mxGetClassID(mat) != mxINDEX_CLASS || - mxIsComplex(mat)) - { - mexErrMsgIdAndTxt("Damkjer:destroyHandleTo:invalidHandle", - "Input must be real-valued index-class scalar."); - } - - ClassHandle* handle = - reinterpret_cast*>(*((mwIndex*)mxGetData(mat))); - - if (!(handle->isValid())) - { - mexErrMsgIdAndTxt("Damkjer:destroyHandleTo:invalidHandle", - "Handle not valid."); - } - - delete handle; -} +// ClassHandle::~ClassHandle +//> Destroy the ClassHandle object and perform clean-up activities. +// +// Free resources for the ClassHandle object and invoke mexUnock to allow +// calling MEX files to be cleared after memory management tasks have +// completed. +// +// @tparam ObjectT The wrapped object type. +//< +//***************************************************************************** +template +inline +ClassHandle::~ClassHandle() +{ + delete thePointer; + thePointer = 0; + + mexUnlock(); +} + +//***************************************************************************** +// ClassHandle::isValid() +//> Perform a validity check on the ClassHandle object. +// +// This method returns true if and only if the ClassHandle object passes +// validity checks. This method prevents the arbitrary reinterpretation of +// non-ClassWHandle objects. +// +// @tparam ObjectT The wrapped object type. +// @returns true if and only if the ClassHandle object passes +// validity checks. +//< +//***************************************************************************** +template +inline +bool +ClassHandle::isValid() const +{ + return (theSignature == typeid(ObjectT).name()); +} + +//***************************************************************************** +// ClassHandle::ClassHandle(ObjectT* const) +//> Initialize a ClassHandle with a pointer to an ObjectT object. +// +// This constructor is private to force objects to be created using the +// ptrAsMat named constructor idiom. This also forces ClassHandles to be +// allocated on the heap instead of on the stack. This method is responsible +// for invoking mexLock to prevent MATLAB from arbitrarily clearing memory +// managed by the wrapper. +// +// @tparam ObjectT The wrapped object type. +// @param aPointer A pointer to an object to be wrapped with a ClassHandle. +//< +//***************************************************************************** +template +inline +ClassHandle::ClassHandle(ObjectT* aPointer) + : thePointer(aPointer) + , theSignature(typeid(ObjectT).name()) +{ + mexLock(); +} + } Index: Damkjer/Util/MATLAB/ClassHandle.hpp =================================================================== --- Damkjer/Util/MATLAB/ClassHandle.hpp (revision 9) +++ Damkjer/Util/MATLAB/ClassHandle.hpp (revision 12) @@ -1,24 +1,20 @@ -//***************************************************************************** -// FILE: ClassHandle.cpp +//**************************************************************************** +// FILE: ClassHandle.hpp // -// Copyright (C) 2012 Kristian Damkjer. +// Copyright (C) 2012 Kristian L. Damkjer. // -// DESCRIPTION: This class is intended to be used to wrap C++ objects for -// transport across mex function calls in MATLAB. +// DESCRIPTION: +//> The template implementation for C++ class handle objects. +//< // -// LIMITATIONS: To preserve the lifetime guarantees of the pointer, default -// construction, copy construction and assignment are -// explicitly disallowed. -// -// The class handle owns the pointer it contains. Thus, when -// the class handle is destroyed, the pointer is deleted. -// -// Class handles are forced to be allocated on the heap by -// using the named constructor idiom. Class handles should be -// destroyed using the destroyHandleTo template function. +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: //> 2012-OCT-08 K. Damkjer // Initial Coding. +// 2013-JUN-24 K. Damkjer +// Clarified Error ID. //< //***************************************************************************** @@ -26,44 +22,113 @@ #include "ClassHandle.h" -#include - namespace Damkjer { -#define CLASS_HANDLE_SIGNATURE 0xfacade01 +//***************************************************************************** +// ClassHandle::createHandle(ObjectT* const) +//> Create a MathWorks index handle to the argument. +// +// Safely encapsulate a pointer to a C++ object as a MathWorks matrix for +// persistence between MEX function calls. +// +// @note +// This function is a named constructor for ClassHandle objects. +// +// @tparam ObjectT The wrapped object type. +// @param aPointer A pointer to an object to be wrapped with a +// ClassHandle. +// @returns A pointer to a MATLAB matrix object holding the pointer +// to the wrapped object handle encoded as an a MathWorks +// index value. +//< +//***************************************************************************** +template +mxArray* +ClassHandle::createHandle(ObjectT* aPointer) +{ + mxArray* aMatrix = mxCreateNumericMatrix(1, 1, mxINDEX_CLASS, mxREAL); -//***************************************************************************** -// ClassHandle::ClassHandle -//***************************************************************************** -template -inline ClassHandle::ClassHandle(BASE* pointer) - : thePointer(pointer) - , theName(typeid(BASE).name()) - , theSignature(CLASS_HANDLE_SIGNATURE) -{ - mexLock(); + *(static_cast(mxGetData(aMatrix))) = + reinterpret_cast(new HandleT(aPointer)); + + return aMatrix; } //***************************************************************************** -// ClassHandle::~ClassHandle +// ClassHandle::object(const mxArray* const) +//> Reinterpret a MathWorks index as a C++ object reference. +// +// @tparam ObjectT The wrapped object type. +// @param aMatrix A MathWorks matrix containing a single index value to be +// reinterpretted as a reference to an object of type +// ObjectT. +// @returns A reference the wrapped object of type ObjectT. +//< //***************************************************************************** -template -inline ClassHandle::~ClassHandle() +template +const ObjectT& +ClassHandle::handleReference(const mxArray* aMatrix) { - delete thePointer; - thePointer = 0; - theSignature = 0; + if (mxGetNumberOfElements(aMatrix) != 1 || + mxGetClassID(aMatrix) != mxINDEX_CLASS || + mxIsComplex(aMatrix)) + { + mexErrMsgIdAndTxt("Damkjer:matAsObj:invalidHandle", + "Input must be real-valued index-class scalar."); + } - mexUnlock(); + HandleT* handle = + reinterpret_cast(*(static_cast(mxGetData(aMatrix)))); + + if (handle == 0 || !handle->isValid()) + { + mexErrMsgIdAndTxt("Damkjer:matAsObj:invalidHandle", + "Handle not valid."); + } + + return handle->object(); } //***************************************************************************** -// ClassHandle::isValid +// ClassHandle::destroyHandle(const mxArray*) +//> Free resources for the handle object represented by the MathWorks index. +// +// @note +// The mxArray argument is intentionally a non-const pointer to a const +// mxArray. This signature matches the expected signature for handles passed +// through the MEX gateway function (mexFunction) on the right-hand side. It +// is very important that the right-hand side arrays be treated as const and +// that the memory not be explicitly cleared here. MATLAB will destruct and +// deallocate the mxArrays when the MEX file is cleared. +// +// @tparam ObjectT The wrapped object type. +// @param aMatrix A MathWorks matrix containing a single index value to be +// reinterpretted as a reference to an object of type +// ObjectT. +//< //***************************************************************************** -template -inline bool ClassHandle::isValid() const +template +void +ClassHandle::destroyHandle(const mxArray* aMatrix) { - return (theSignature == CLASS_HANDLE_SIGNATURE && - theName == typeid(BASE).name()); + if (mxGetNumberOfElements(aMatrix) != 1 || + mxGetClassID(aMatrix) != mxINDEX_CLASS || + mxIsComplex(aMatrix)) + { + mexErrMsgIdAndTxt("Damkjer:destroyHandleTo:invalidHandle", + "Input must be real-valued index-class scalar."); + } + + HandleT* handle = + reinterpret_cast(*(static_cast(mxGetData(aMatrix)))); + + if (handle == 0 || !handle->isValid()) + { + mexErrMsgIdAndTxt("Damkjer:destroyHandleTo:invalidHandle", + "Handle not valid."); + } + + delete handle; + handle = 0; } Index: Damkjer/Util/MATLAB/VpTree.m =================================================================== --- Damkjer/Util/MATLAB/VpTree.m (revision 12) +++ Damkjer/Util/MATLAB/VpTree.m (revision 12) @@ -0,0 +1,202 @@ +% VpTree Vantage Point Tree spatial indexing data structure +% +% File: VpTree.m +% +% Description: +% This MATLAB class represents a vantage-point tree data structure. The +% class is derived from the MATLAB handle class to provide automated object +% descruction on calls to "clear". +% +% Limitations: +% See VpTree.h for complete description of limitations. +% +% Properties: +% None. +% +% Methods: +% [tree] = VpTree(varargin) - VP Tree Constructor +% delete(tree) - Release this object and +% free memory. +% [idx,dist] = knn(this, queries, k, varargin) - Perform a k-nearest +% neighbor search against +% the tree. +% [idx,dist] = rnn(this, data, radius) - Perform a fixed-radius +% nearest neighbor search +% against the tree. +% +% Toolbox requirements: +% None. +% +% Script requirements: +% None. +% +% Data requirements: +% VpTreeAPI MEX library. +% +% References: +% Yianilos, P. N. (1993). Data Structures and Algorithms for Nearest +% Neighbor Search in General Metric Spaces. In Proceedings of the Fourth +% Annual ACM-SIAM Symposium on Discrete Algorithms (pp. 311–321). SODA +% ’93. Philadelphia, PA, USA: Society for Industrial and Applied +% Mathematics. http://dl.acm.org/citation.cfm?id=313559.313789 +% +% See Also: +% None. +% + +% Copyright (C) 2012 Kristian L. Damkjer. +% +% Software History: +% 2012-AUG-29 K. Damkjer +% Initial Coding. +% + +%****************************************************************************** +% CLASS: VpTree +% Vantage Point Tree spatial indexing data structure. The class is derived +% from the MATLAB handle class to provide automated object descruction on +% calls to "clear". +%****************************************************************************** +classdef (Sealed = true) VpTree < handle + + properties (Hidden=true, Access = private) + % The C++ VP-tree object owned by this handle class. + theTree + end + + methods + %************************************************************************ + % VpTree/VpTree + %************************************************************************ + function this = VpTree(varargin) + % Build the index structure for the database. + % + % Parameters: + % varargin - Variable-length input argument list. Currently, only a + % single argument is permitted in the argument list. + % Specifically, a set of point observations that will be + % spatially indexed by the tree structure. + + if (nargin ~= 1) + error('VpTree:InvalidArgumentList',... + 'VpTree must be constructed with a set of observations'); + end + + this.theTree = VpTreeAPI('create', varargin{1}); + end + + %************************************************************************ + % VpTree/delete + %************************************************************************ + function delete(this) + % This function frees memory on delete (clear) of the VpTree. + VpTreeAPI('destroy', this.theTree); + end + + %************************************************************************ + % VpTree/knn + %************************************************************************ + function [idx,dist] = knn(this, queries, k, varargin) + % Perform a k-nearest neighbor search on the database with the + % set of queries. + % + % Parameters: + % queries - The set of search locations about which to establish + % k-nearest neighborhoods. + % + % k - The number of nearest neighbors to find for the + % neighborhood. + % + % varargin - Variable-length input argument list. The only defined + % argument at this time is 'limit' which is used to + % establish an upper bound on the radius of the + % k-nearest neighborhood. + % + % Returns: + % idx - The indices for the k-nearest neighbors, sorted by + % distance to the query, for each of the input query points. + % + % dist - The distance to each k-nearest neighbor, sorted by + % distance to the query, for each of the input query points. + + userParams = struct('limit', realmax); + + % Parse the Property/Value pairs + if rem(length(varargin), 2) ~= 0 + error('Damkjer:PropertyValueNotPair', ... + ['Additional arguments must take the form of'... + 'Property/Value pairs']); + end + + propertyNames = {'limit'}; + + while ~isempty(varargin) + property = varargin{1}; + value = varargin{2}; + + % If the property has been supplied in a shortened form, + % lengthen it + iProperty = find(strncmpi(property, propertyNames, ... + length(property))); + + if isempty(iProperty) + error('Damkjer:InvalidProperty', 'Invalid Property'); + elseif length(iProperty) > 1 + error('Damkjer:AmbiguousProperty', ... + 'Supplied shortened property name is ambiguous'); + end + + property = propertyNames{iProperty}; + + switch property + case 'limit' + if (isscalar(value) && isnumeric(value) && ... + isreal(value) && value > 0) + userParams.limit = value; + else + error('Damkjer:InvalidLimit', ... + 'Limit must be a real valued positive scalar'); + end + end + + varargin(1:2) = []; + end + + if (nargout == 1) + idx = VpTreeAPI('search_kann', this.theTree,... + queries, k, userParams.limit); + else + [idx,dist] = VpTreeAPI('search_kann', this.theTree,... + queries, k, userParams.limit); + end + end + + %************************************************************************ + % VpTree/rnn + %************************************************************************ + function [idx,dist] = rnn(this, queries, radius) + % Perform a fixed-radius nearest neighbor search on the + % database with the set of queries. + % + % Parameters: + % queries - The set of search locations about which to establish + % k-nearest neighborhoods. + % + % radius - The maximum permitted distance to a nearest neighbor. + % + % Returns: + % idx - The indices for the k-nearest neighbors, sorted by + % distance to the query, for each of the input query points. + % + % dist - The distance to each k-nearest neighbor, sorted by + % distance to the query, for each of the input query points. + if (nargout == 1) + idx = VpTreeAPI('search_frann', this.theTree, queries, radius); + else + [idx,dist] = VpTreeAPI('search_frann', this.theTree,... + queries, radius); + end + end + end +end + Index: Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.cpp =================================================================== --- Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.cpp (revision 12) +++ Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.cpp (revision 12) @@ -0,0 +1,789 @@ +//***************************************************************************** +// FILE: VpTreeAPI.cpp +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The application interface for working with VP Trees in MATLAB. +//< +// +// LIMITATIONS: +//> All interfaces to the VP Tree objects from MATLAB must be routed through +// this gateway file. This interface is required until and unless MATLAB +// provides a mechanism for modifying locks on MEX files other than the +// current file. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-19 K. Damkjer +// Improved structure and documentation. Prevented double free of +// VP Tree memory and infinite locking of MEX library. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** + +#if _OPENMP +#include +#endif + +#include "MATLAB/ClassHandle.h" +#include "Util/SpatialIndexing/VpTree/VpTree.h" // USES + +//*** +// Fix "wide char" definition for older versions of MATLAB. This must be placed +// after other includes and before the mex.h include. +//*** +#if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) + #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) + #define CHAR16_T + #endif +#endif + +#include "mex.h" + +//***************************************************************************** +// NAMESPACE: +//> Vantage Point Tree MEX API types, interfaces, and implementations. +//< +//***************************************************************************** +namespace +{ + +typedef double CoordT; + //> The MATLAB VpTree point coordinate type. + //< + +typedef std::vector PointT; + //> The MATLAB VpTree point type. + //< + +typedef std::deque PointSetT; + //> The MATLAB VpTree point set type. + //< + +typedef Damkjer::EuclideanDistance MetricT; + //> The MATLAB VpTree distance metric type. + //< + +typedef Damkjer::VpTree TreeT; + //> The MATLAB VpTree type. + //< + +typedef Damkjer::ClassHandle HandleT; + //> The VpTree MATLAB Class Handle type. + //< + +//***************************************************************************** +// FUNCTION: vpTreeCreate +//> Create a VpTree for use in MATLAB. +// +// New objects are wrapped by the ClassHandle template to ensure that locks +// are managed correctly to avoid double frees of memory managed by this +// class, to ensure objects have a life span separate from this function's +// scope, and to provide convenience methods for passing the pointer to the +// object between MATLAB and C++. +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** +void +vpTreeCreate(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) +{ + //*** + // Check parameters. Remember that we always have one "extra" input + // parameter to handle function dispatching through the MEX gateway. It + // always occupies the first input parameter position. + //*** + if (nrhs < 2 || nrhs > 2) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:nargin", + "The vpTreeCreate function requires a single input."); + } + + if (nlhs > 1) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:nargout", + "The vpTreeCreate function requires a single output."); + } + + //*** + // The single input required by vpTreeCreate is the collection of points to + // be indexed. + //*** + const mxArray* points=prhs[1]; + + // Check to make sure that points are real-valued numerics + if (mxIsSparse(points) || + mxGetNumberOfDimensions(points) != 2 || + mxIsComplex(points) || + !mxIsNumeric(points)) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:prhs", + "Input to vpTreeCreate must be a full, 2-D matrix " + "of real-valued data representing N-dimensional " + "observations."); + } + + // Attempt to make the VP Tree. + const mwSize dims = mxGetM(points); + const mwSize elems = mxGetN(points); + + double* data = mxGetPr(points); + + //*** + // Selection of data structure for the point database is not arbitrary. + // + // 1. Point coordinates are passed in as double-precision values. Preserve + // the data fidelity. + // 2. Individual points are often low-dimensional. Keep the coordinates for + // a single point in contiguous memory by using a std::vector container. + // 3. The point database can be quite large. Since VP Tree is an online data + // structure, allow references to points to occupy non-contiguous memory. + // This also speeds construction and destruction of the point database. + //*** + PointSetT pointData(elems, PointT(dims)); + + for (mwSize elem = elems; elem --> 0;) + { + for (mwSize dim = dims; dim --> 0;) + { + pointData[elem][dim]=(CoordT)(data[elem*dims+dim]); + } + } + + //*** + // Use the ClassHandle named constructor to provide a handle to the new VP + // Tree object. + //*** + try + { + plhs[0] = HandleT::createHandle(new TreeT(pointData, MetricT())); + } + catch (const std::exception& e) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:initError", e.what()); + } +} + +//***************************************************************************** +// FUNCTION: vpTreeDestroy +//> Destroy the VpTree referenced by a ClassHandle object. +// +// Destroying objects through the ClassHandle wrapper ensures memory leaks +// are not introduced through this MEX function and allows the MEX library +// to be unlocked once all objects have been destroyed and their memory +// returned to the system. +// +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** +inline +void +vpTreeDestroy(int nrhs, const mxArray** prhs) +{ + //*** + // Check parameters. Remember that we always have one "extra" input + // parameter to handle function dispatching through the MEX gateway. It + // always occupies the first input parameter position. + //*** + if (nrhs != 2 || !mxIsNumeric(prhs[1])) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeDestroy:varargin", + "The vpTreeDestroy function requires a single " + "input."); + } + + // Free the VP Tree through the ClassHandle named destructor. + HandleT::destroyHandle(prhs[1]); +} + +//***************************************************************************** +// FUNCTION: vpTreeFRANN +//> Perform a fixed-radius all nearest neighbor (FRANN) search on a VpTree. +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** +void +vpTreeFRANN(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) +{ + //*** + // Check parameters. Remember that we always have one "extra" input + // parameter to handle function dispatching through the MEX gateway. It + // always occupies the first input parameter position. + //*** + if (nrhs < 3 || nrhs > 4 || !mxIsNumeric(prhs[1])) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:varargin", + "Invalid number of input arguments."); + } + + if (nlhs>2) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:varargout", + "Invalid number of output arguments."); + } + + // Retrieve the tree object through the ClassHandle helper method. + const TreeT& tree = HandleT::handleReference(prhs[1]); + + // The second parameter should be the query points. + const mxArray* queries=prhs[2]; + + // Check to make sure that query points are real-valued numerics + if (mxIsSparse(queries) || + mxGetNumberOfDimensions(queries) != 2 || + mxIsComplex(queries) || + !mxIsNumeric(queries)) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:prhs", + "Second input parameter to vpTreeFRANN must be a " + "full, 2-D matrix of real-valued data representing " + "multi-dimensional queries."); + } + + // The third parameter should be the query radius. + const mxArray* rData=prhs[3]; + + // Check to make sure that radius is a real-valued numeric scalar. + if (mxIsSparse(rData) || + mxGetNumberOfElements(rData) != 1 || + mxIsComplex(rData) || + !mxIsNumeric(rData)) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:prhs", + "Third input parameter to vpTreeFRANN must be a " + "real-valued scalar representing desired neighborhood " + "radius limit."); + } + + //*** + // Get the query points. + // + // Selection of data structure for the query database is not arbitrary. + // + // 1. Point coordinates are passed in as double-precision values. Preserve + // the data fidelity. + // 2. Individual points are often low-dimensional. Keep the coordinates for + // a single point in contiguous memory by using a std::vector container. + // 3. The query database can be quite large. Allow references to points to + // occupy non-contiguous memory. + //*** + const mwSize dims = mxGetM(queries); + const mwSize elems = mxGetN(queries); + + double* data = mxGetPr(queries); + PointSetT queryData(elems, PointT(dims)); + + for (mwIndex elem = elems; elem --> 0;) + { + for (mwIndex dim = dims; dim --> 0;) + { + queryData[elem][dim]=(CoordT)(data[elem*dims+dim]); + } + } + + // Get the desired neighborhood radius limit. + TreeT::DistT radius = (TreeT::DistT)(*(double*)mxGetData(rData)); + + //*** + // The first output parameter holds the nearest neighbor indices. This + // collection is represented as a cell array of vectors with a cell for each + // query point. + //*** + plhs[0] = mxCreateCellMatrix(elems, 1); + + //*** + // If desired, the distance from the query point to each of the nearest + // neighbors can also be provided. This collection is represented as a cell + // array of vectors with a cell for each query point. + //*** + if (nlhs==2) + { + plhs[1] = mxCreateCellMatrix(elems, 1); + } + + //*** + // The following logic flows may seem counter-intuitive, but are structured + // to intentionally avoid nested critical sections in parallelized code. + // + // Unfortunately, any calls to the MATLAB API must be treated as belonging + // to a critical section since none of the API is thread-safe. + //*** + +#if _OPENMP + if (omp_get_num_threads() == 1) + { + omp_set_dynamic(1); + omp_set_num_threads(omp_get_num_procs()); + } +#endif + + //*** + // The VP Tree data structure always provides results as a set of pairs of + // indices and distances. There is no performance benefit to omitting the + // distance computations since they are required for the search algorithm. + //*** + std::deque results(queryData.size()); + + //*** + // The first embarassingly parallelizable section simply searches for each + // query point's neighbors in parallel. This is much simpler than attempting + // to parallelize the search for a single point, and likely to yield + // superior results. + //*** + #pragma omp parallel for + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + results[uq] = tree.rnn(queryData[uq], radius); + } + + //*** + // Allocating memory for the results to be passed back to MATLAB must take + // place in a "critical section" since it involves exercising the MEX API. + //*** + std::deque nbr_idxs; + std::deque point_idxs; + + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + mwSize neighbors = results[uq].first.size(); + + nbr_idxs.push_back(mxCreateNumericMatrix(0, 0, mxINDEX_CLASS, mxREAL)); + mxSetM(nbr_idxs[uq], neighbors); + mxSetN(nbr_idxs[uq], 1); + mxSetData(nbr_idxs[uq], mxMalloc(sizeof(mwIndex)*neighbors*1)); + + point_idxs.push_back((mwIndex*)mxGetData(nbr_idxs[uq])); + } + + //*** + // Once memory has been allocated, the actual results can be populated in + // parallel. + //*** + #pragma omp parallel for + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + mwSize neighbors = results[uq].first.size(); + + mwIndex* idxs = point_idxs[uq]; + + for (mwIndex idx = neighbors; idx --> 0;) + { + idxs[idx]=results[uq].first[idx]+1; + } + } + + //*** + // Marking the data for return to MATLAB must take place in a "critical + // section" since it involves exercising the MEX API. This also changes + // ownership and memory management responsibilities to MATLAB. We will not + // free this data. + //*** + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mxSetCell(plhs[0], q, nbr_idxs[q]); + } + + // Repeat the "hand-off" to MATLAB for distance data, if it was requested. + if (nlhs==2) + { + //*** + // Allocating memory for the results to be passed back to MATLAB must + // take place in a "critical section" since it involves exercising the + // MEX API. + //*** + std::deque nbr_dists; + std::deque point_dists; + + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mwSize neighbors = results[q].first.size(); + + nbr_dists[q] = mxCreateDoubleMatrix(0, 0, mxREAL); + mxSetM(nbr_dists[q], neighbors); + mxSetN(nbr_dists[q], 1); + mxSetData(nbr_dists[q], mxMalloc(sizeof(double)*neighbors*1)); + + point_dists.push_back(mxGetPr(nbr_dists[q])); + } + + //*** + // Once memory has been allocated, the actual results can be populated in + // parallel. + //*** + #pragma omp parallel for + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + mwSize neighbors = results[uq].first.size(); + + double* dists = point_dists[uq]; + + for (mwIndex idx = neighbors; idx --> 0;) + { + dists[idx]=results[uq].second[idx]; + } + } + + //*** + // Marking the data for return to MATLAB must take place in a "critical + // section" since it involves exercising the MEX API. This also changes + // ownership and memory management responsibilities to MATLAB. We will + // not free this data. + //*** + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mxSetCell(plhs[1], q, nbr_dists[q]); + } + } +} + +//***************************************************************************** +// FUNCTION: vpTreeKANN +//> Perform a k all nearest neighbor (KANN) search on a VpTree. +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** +void +vpTreeKANN(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) +{ + //*** + // Check parameters. Remember that we always have one "extra" input + // parameter to handle function dispatching through the MEX gateway. It + // always occupies the first input parameter position. + //*** + if (nrhs != 5 || !mxIsNumeric(prhs[1])) + { + mexErrMsgIdAndTxt("Damkjer:kannVpTree:varargin", + "Invalid number of arguments"); + } + + // Retrieve the tree object through the ClassHandle helper method. + const TreeT& tree = HandleT::handleReference(prhs[1]); + + // The second parameter should be the query points. + const mxArray* queries=prhs[2]; + + // Check to make sure that query points are real-valued numerics. + if (mxIsSparse(queries) || + mxGetNumberOfDimensions(queries) != 2 || + mxIsComplex(queries) || + !mxIsNumeric(queries)) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeKANN:prhs", + "Second input parameter to vpTreeKANN must be a full, " + "2-D matrix of real-valued data representing " + "multi-dimensional queries."); + } + + // The third parameter should be the desired neighborhood cardinality. + const mxArray* kData=prhs[3]; + + // Check to make sure that cardinality is a real-valued numeric scalar. + if (mxIsSparse(kData) || + mxGetNumberOfElements(kData) != 1 || + mxIsComplex(kData) || + !mxIsNumeric(kData)) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeKANN:prhs", + "Third input parameter to vpTreeKANN must be an " + "real-valued scalar representing desired neighborhood " + "cardinality."); + } + + // The fourth parameter should be the desired radius limit. + const mxArray* rData=prhs[4]; + + // Check to make sure that radius is a real-valued numeric scalar. + if (mxIsSparse(rData) || + mxGetNumberOfElements(rData) != 1 || + mxIsComplex(rData) || + !mxIsNumeric(rData)) + { + mexErrMsgIdAndTxt("Damkjer:vpTreeKANN:prhs", + "Fourth input parameter to vpTreeKANN must be an " + "real-valued scalar representing desired neighborhood " + "radius limit."); + } + + //*** + // Get the query points. + // + // Selection of data structure for the query database is not arbitrary. + // + // 1. Point coordinates are passed in as double-precision values. Preserve + // the data fidelity. + // 2. Individual points are often low-dimensional. Keep the coordinates for + // a single point in contiguous memory by using a std::vector container. + // 3. The query database can be quite large. Allow references to points to + // occupy non-contiguous memory. + //*** + const mwSize dims = mxGetM(queries); + const mwSize elems = mxGetN(queries); + + double* data = mxGetPr(queries); + PointSetT queryData(elems, PointT(dims)); + + for (mwIndex elem = elems; elem --> 0;) + { + for (mwIndex dim = dims; dim --> 0;) + { + queryData[elem][dim]=(CoordT)(data[elem*dims+dim]); + } + } + + // Get the desired neighborhood cardinality. + mwSize k = (mwSize)(*((double*)mxGetData(kData))); + + // Get the desired neighborhood radius limit. + TreeT::DistT radius = (TreeT::DistT)(*(double*)mxGetData(rData)); + + //*** + // The first output parameter holds the nearest neighbor indices. This + // collection is represented as a cell array of vectors with a cell for each + // query point. + //*** + plhs[0] = mxCreateCellMatrix(elems, 1); + + //*** + // If desired, the distance from the query point to each of the nearest + // neighbors can also be provided. This collection is represented as a cell + // array of vectors with a cell for each query point. + //*** + if (nlhs==2) + { + plhs[1] = mxCreateCellMatrix(elems, 1); + } + + //*** + // The following logic flows may seem counter-intuitive, but are structured + // to intentionally avoid nested critical sections in parallelized code. + // + // Unfortunately, any calls to the MATLAB API must be treated as belonging + // to a critical section since none of the API is thread-safe. + //*** + +#if _OPENMP + if (omp_get_num_threads() == 1) + { + omp_set_dynamic(1); + omp_set_num_threads(omp_get_num_procs()); + } +#endif + + //*** + // The VP Tree data structure always provides results as a set of pairs of + // indices and distances. There is no performance benefit to omitting the + // distance computations since they are required for the search algorithm. + //*** + std::deque results(queryData.size()); + + //*** + // The first embarassingly parallelizable section simply searches for each + // query point's neighbors in parallel. This is much simpler than attempting + // to parallelize the search for a single point, and likely to yield + // superior results. + //*** + #pragma omp parallel for + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + results[uq] = tree.knn(queryData[uq], k, radius); + } + + //*** + // Allocating memory for the results to be passed back to MATLAB must take + // place in a "critical section" since it involves exercising the MEX API. + //*** + std::deque nbr_idxs; + std::deque point_idxs; + + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mwSize neighbors = results[q].first.size(); + + nbr_idxs.push_back(mxCreateNumericMatrix(0, 0, mxINDEX_CLASS, mxREAL)); + mxSetM(nbr_idxs[q], neighbors); + mxSetN(nbr_idxs[q], 1); + mxSetData(nbr_idxs[q], mxMalloc(sizeof(mwIndex)*neighbors*1)); + + point_idxs.push_back((mwIndex*)mxGetData(nbr_idxs[q])); + } + + //*** + // Once memory has been allocated, the actual results can be populated in + // parallel. + //*** + #pragma omp parallel for + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + mwSize neighbors = results[uq].first.size(); + + mwIndex* idxs = point_idxs[uq]; + + for (mwIndex idx = neighbors; idx --> 0;) + { + idxs[idx]=results[uq].first[idx]+1; + } + } + + //*** + // Marking the data for return to MATLAB must take place in a "critical + // section" since it involves exercising the MEX API. This also changes + // ownership and memory management responsibilities to MATLAB. We will not + // free this data. + //*** + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mxSetCell(plhs[0], q, nbr_idxs[q]); + } + + // Repeat the "hand-off" to MATLAB for distance data, if it was requested. + if (nlhs==2) + { + //*** + // Allocating memory for the results to be passed back to MATLAB must + // take place in a "critical section" since it involves exercising the + // MEX API. + //*** + std::deque nbr_dists; + std::deque point_dists; + + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mwSize neighbors = results[q].first.size(); + + nbr_dists[q] = mxCreateDoubleMatrix(0, 0, mxREAL); + mxSetM(nbr_dists[q], neighbors); + mxSetN(nbr_dists[q], 1); + mxSetData(nbr_dists[q], mxMalloc(sizeof(double)*neighbors*1)); + + point_dists.push_back(mxGetPr(nbr_dists[q])); + } + + //*** + // Once memory has been allocated, the actual results can be populated in + // parallel. + //*** + #pragma omp parallel for + for (int q = 0; q < queryData.size(); ++q) + { + unsigned int uq = static_cast(q); + mwSize neighbors = results[uq].first.size(); + + double* dists = point_dists[uq]; + + for (mwIndex idx = neighbors; idx --> 0;) + { + dists[idx]=results[uq].second[idx]; + } + } + + //*** + // Marking the data for return to MATLAB must take place in a "critical + // section" since it involves exercising the MEX API. This also changes + // ownership and memory management responsibilities to MATLAB. We will + // not free this data. + //*** + for (unsigned int q = 0; q < queryData.size(); ++q) + { + mxSetCell(plhs[1], q, nbr_dists[q]); + } + } +} + +} + +//***************************************************************************** +// FUNCTION: mexFunction +//> The MATLAB Executable Gateway Function. +// +// Provides the application interface for working with VP Trees in MATLAB. +// All functional interfaces are routed through this single function to +// ensure locks and memory management are handled properly by MATLAB. +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** +void +mexFunction(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) +{ + //*** + // This MEX function should always have at least one input parameter to + // handle function dispatching through the MEX gateway. + //*** + if (nrhs < 1) + { + mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:nargin", + "VpTreeAPI requires at least one input which " + "specifies the operation to be performed."); + } + + // The operation switch is simply a string. + char* operation = mxArrayToString(prhs[0]); + + if (!operation) + { + mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:InvalidOperation", + "Invalid mode supplied to VpTreeAPI."); + return; // error should force return. + } + + // Dispatch to helper functions. Err if operation is not recognized. + if (!strcmp("create", operation)) + { + vpTreeCreate(nlhs, plhs, nrhs, prhs); + + } + else if (!strcmp("destroy", operation)) + { + if (nlhs != 0) + { + mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:nargout", + "Nothing to return."); + } + + vpTreeDestroy(nrhs, prhs); + } + else if (!strcmp("search_frann", operation)) + { + vpTreeFRANN(nlhs, plhs, nrhs, prhs); + } + else if (!strcmp("search_kann", operation)) + { + vpTreeKANN(nlhs, plhs, nrhs, prhs); + } + else + { + mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:UnknownOperation", + "Unrecognized mode provided to VpTreeAPI."); + } + + // Prevent a slow memory leak. + mxFree(operation); +} Index: Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.vcxproj =================================================================== --- Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.vcxproj (revision 12) +++ Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.vcxproj (revision 12) @@ -0,0 +1,284 @@ + + + + + DebugOMP + Win32 + + + DebugOMP + x64 + + + Debug + Win32 + + + Debug + x64 + + + OpenMP + Win32 + + + OpenMP + x64 + + + Release + Win32 + + + Release + x64 + + + + + + + + {20fe2624-c64f-d61a-bd8f-1725a8e68a42} + + + + Win32Proj + VpTreeAPI + + + + DynamicLibrary + true + + + DynamicLibrary + true + + + DynamicLibrary + true + + + DynamicLibrary + true + + + DynamicLibrary + false + + + DynamicLibrary + false + + + DynamicLibrary + false + + + DynamicLibrary + false + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + .mexw32 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw32 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw64 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw64 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw32 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw32 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw64 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + .mexw64 + $(SolutionDir)lib\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + + + _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN32;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDLL + Level4 + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + + + MachineX86 + true + true + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN32;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDLL + Level4 + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + AnySuitable + true + Speed + + + MachineX86 + true + true + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN64;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDLL + Level4 + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + + + true + true + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + + + + + _USE_MATH_DEFINES;WIN64;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDLL + Level4 + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + /wd4514 /wd4571 /wd4668 /wd4710 /wd4711 /wd4820 /wd4986 %(AdditionalOptions) + AnySuitable + true + Speed + + + true + true + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + + + + + + Index: Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.vcxproj.filters =================================================================== --- Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.vcxproj.filters (revision 12) +++ Damkjer/Util/MATLAB/VpTreeAPI/VpTreeAPI.vcxproj.filters (revision 12) @@ -0,0 +1,18 @@ + + + + + {4010ed24-e68d-4e6e-97b0-8b8bb335aa86} + cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx + + + {0c039d31-de79-478b-9dc5-c3378145e52a} + h;hpp;hxx;hm;inl;inc;xsd + + + + + Source Files + + + Index: Damkjer/Util/MATLAB/VpTreeAPI/makeVpTree.m =================================================================== --- Damkjer/Util/MATLAB/VpTreeAPI/makeVpTree.m (revision 12) +++ Damkjer/Util/MATLAB/VpTreeAPI/makeVpTree.m (revision 12) @@ -0,0 +1,121 @@ +% makeVpTree Build VpTree spatial indexing library MEX functions and classes. +% +% File: +% makeVpTree.m +% +% Description: +% This MATLAB function provides an simplified interface for building the +% VpTree C++ and MEX files. +% +% Limitations: +% Assumes mex -setup has been successfully run. +% +% Synopsis: +% makeVpTree(options...) +% +% Inputs: +% Option strings may be provided as abbreviations as long as they resolve to +% a unique option. +% +% 'debug' - Compile with debug flags and fully populated symbol table. +% 'parallel' - Enable OpenMP pragmas for multi-threaded computing. +% 'verbose' - Provide verbose output while compiling. +% 'warnings' - Provide compiler warning output for production-ready code. +% Implies 'verbose'. +% +% Outputs: +% None. +% +% Toolbox requirements: +% None. +% +% Code requirements: +% None. +% +% Data requirements: +% None. +% +% References: +% None. +% +% See Also: +% VpTree +% + +% Software History: +% 2012-AUG-29 K. Damkjer +% Initial Coding. +% 2013-JUN-17 K. Damkjer +% Additional Commenting. +% + +function makeVpTree(varargin) + +command = 'mex -largeArrayDims -DTEMPLATE_INCLUSION'; + +matlab_ver = regexp(version, '[. ]', 'split'); +command = [command... + ' -DMATLAB_MAJOR=' matlab_ver{1}... + ' -DMATLAB_MINOR=' matlab_ver{2}... + ' -DMATLAB_REVIS=' matlab_ver{3}... + ' -DMATLAB_BUILD=' matlab_ver{4}... + ' -DMATLAB_REL=' matlab_ver{5}(2:end-1)]; + +flags = {'verbose', 'debug', 'warnings', 'parallel'}; +options = ''; + +while ~isempty(varargin) + flag = varargin{1}; + + % If the property has been supplied in a shortened form, lengthen it + iFlag = find(strncmpi(flag, flags, length(flag))); + + if isempty(iFlag) + % Pass through any arguments we don't recognize + options = strcat(options, ' ', flag); + + % Alternatively, escalate to an error. + %error('Damkjer:makeVpTree:InvalidFlag', ['Invalid Flag: ' flag]); + elseif length(iFlag) > 1 + error('Damkjer:makeVpTree:AmbiguousFlag', ... + ['Supplied shortened flag is ambiguous: ' flag]); + else + flag = flags{iFlag}; + + switch flag + case 'verbose' + command = strcat(command, ' -v'); + case 'debug' + command = strcat(command, ' -g'); + case 'parallel' + if (ispc) + command = strcat(command, ' COMPFLAGS="$COMPFLAGS /openmp"'); + else + command = strcat(command, ' CFLAGS="\$CFLAGS -fopenmp"',... + ' CXXFLAGS="\$CXXFLAGS -fopenmp"',... + ' LDFLAGS="\$LDFLAGS -fopenmp"'); + end + case 'warnings' + if (ispc) + command = strcat(command, ' -v COMPFLAGS="$COMPFLAGS -W3"'); + else + command = strcat(command, ' -v',... + ' CFLAGS="\$CFLAGS -Wall -Wextra"',... + ' CXXFLAGS="\$CXXFLAGS -Wall -Wextra"'); + end + otherwise + error('Damkjer:makeVpTree:NotImplementedFlag', ... + ['Flag recognized, but not supported: ' flag]); + end + end + + varargin(1) = []; +end + +[path,~,~]=fileparts(mfilename('fullpath')); +command = [command options ' -I' fullfile(path,'..','..','..')... + ' -outdir ' path ' ' path '/']; + +eval([command 'VpTreeAPI.cpp']); + +end Index: Damkjer/Util/Math/fastcenter.cpp =================================================================== --- Damkjer/Util/Math/fastcenter.cpp (revision 9) +++ Damkjer/Util/Math/fastcenter.cpp (revision 12) @@ -1,11 +1,14 @@ -//========================================================================= -// FILE: fastcov.cpp +//***************************************************************************** +// FILE: fastcenter.cpp // // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: This MEX source file provides a fast implementation of -// centering method for cell-arrays of real valued matrices. +// DESCRIPTION: +//> @todo Describe this file +//< // -// LIMITATIONS: Does not work for cell-arrays of complex matrices. +// LIMITATIONS: +//> Does not work for cell-arrays of complex matrices. +//< // // SOFTWARE HISTORY: @@ -13,5 +16,5 @@ // Initial Coding. //< -//========================================================================= +//***************************************************************************** #ifdef _OPENMP @@ -21,4 +24,8 @@ #include +//*** +// Fix "wide char" definition for older versions of MATLAB. This must be placed +// after other includes and before the mex.h include. +//*** #if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) @@ -29,4 +36,16 @@ #include "mex.h" +//***************************************************************************** +// FUNCTION: mexFunction +//> The MATLAB Executable Gateway Function. +// +// @todo Describe this MEX function +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** void mexFunction( int nlhs, mxArray* plhs[], Index: Damkjer/Util/Math/fastcoeffvar.cpp =================================================================== --- Damkjer/Util/Math/fastcoeffvar.cpp (revision 9) +++ Damkjer/Util/Math/fastcoeffvar.cpp (revision 12) @@ -1,11 +1,15 @@ -//========================================================================= +//***************************************************************************** // FILE: fastcoeffvar.cpp // // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: This MEX source file provides a fast implementation of cov -// method for cell-arrays of real valued matrices. +// DESCRIPTION: +//> This MEX source file provides a fast implementation of cov method for +// cell-arrays of real valued matrices. +//< // -// LIMITATIONS: Does not work for cell-arrays of complex matrices. +// LIMITATIONS: +//> Does not work for cell-arrays of complex matrices. +//< // // SOFTWARE HISTORY: @@ -13,5 +17,5 @@ // Initial Coding. //< -//========================================================================= +//***************************************************************************** #ifdef _OPENMP @@ -21,4 +25,8 @@ #include +//*** +// Fix "wide char" definition for older versions of MATLAB. This must be placed +// after other includes and before the mex.h include. +//*** #if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) @@ -29,7 +37,19 @@ #include "mex.h" -void mexFunction( - int nlhs, mxArray* plhs[], - int nrhs, const mxArray* prhs[]) +//***************************************************************************** +// FUNCTION: mexFunction +//> The MATLAB Executable Gateway Function. +// +// Perform a parallelized computation of the coefficient of variance. +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** +void +mexFunction(int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { if (nrhs != 1 || !mxIsCell(prhs[0])) @@ -38,5 +58,5 @@ "Missing or invalid input argument."); } - + if (nlhs > 1) { @@ -44,5 +64,5 @@ "Too many output arguments."); } - + mwSize cells = mxGetNumberOfElements (prhs[0]); @@ -90,4 +110,5 @@ dist[n]+=diff*diff; } + mean+=sqrt(dist[m])*w1; } @@ -97,13 +118,12 @@ for (mwSize n = Ns[cellp]; n --> 0;) { - cov_vals[cellp] = 0; + cov_vals[cellp] = 0; - for (mwSize mc = Ms[cellp]; mc --> 0;) - { - cov_vals[cellp] += - w2 - * (vals[cellp][mc + Ms[cellp] * n]-mean[n] - * (vals[cellp][mc + Ms[cellp] * n]-vals[cellp][Ms[cellp] * n2]); - } + for (mwSize mc = Ms[cellp]; mc --> 0;) + { + cov_vals[cellp] += + w2 + * (vals[cellp][mc + Ms[cellp] * n]-mean[n] + * (vals[cellp][mc + Ms[cellp] * n]-vals[cellp][Ms[cellp] * n2]); } } Index: Damkjer/Util/Math/fastcov.cpp =================================================================== --- Damkjer/Util/Math/fastcov.cpp (revision 9) +++ Damkjer/Util/Math/fastcov.cpp (revision 12) @@ -1,11 +1,14 @@ -//========================================================================= +//***************************************************************************** // FILE: fastcov.cpp // // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: This MEX source file provides a fast implementation of cov -// method for cell-arrays of real valued matrices. -// -// LIMITATIONS: Does not work for cell-arrays of complex matrices. +// DESCRIPTION: +//> @todo Describe this file +//< +// +// LIMITATIONS: +//> Does not work for cell-arrays of complex matrices. +//< // // SOFTWARE HISTORY: @@ -13,5 +16,5 @@ // Initial Coding. //< -//========================================================================= +//***************************************************************************** #ifdef _OPENMP @@ -22,4 +25,8 @@ #include +//*** +// Fix "wide char" definition for older versions of MATLAB. This must be placed +// after other includes and before the mex.h include. +//*** #if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) @@ -30,4 +37,16 @@ #include "mex.h" +//***************************************************************************** +// FUNCTION: mexFunction +//> The MATLAB Executable Gateway Function. +// +// @todo Describe this MEX function +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** void mexFunction( int nlhs, mxArray* plhs[], Index: Damkjer/Util/Math/par_eig.cpp =================================================================== --- Damkjer/Util/Math/par_eig.cpp (revision 9) +++ Damkjer/Util/Math/par_eig.cpp (revision 12) @@ -1,11 +1,14 @@ -//========================================================================= +//***************************************************************************** // FILE: par_eig.cpp // // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: This MEX source file provides a fast implementation of cov -// method for cell-arrays of real valued matrices. +// DESCRIPTION: +//> @todo Describe this file +//< // -// LIMITATIONS: Does not work for cell-arrays of complex matrices. +// LIMITATIONS: +//> Does not work for cell-arrays of complex matrices. +//< // // SOFTWARE HISTORY: @@ -13,5 +16,5 @@ // Initial Coding. //< -//========================================================================= +//***************************************************************************** #ifdef _OPENMP @@ -22,4 +25,8 @@ #include +//*** +// Fix "wide char" definition for older versions of MATLAB. This must be placed +// after other includes and before the mex.h include. +//*** #if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) @@ -32,4 +39,16 @@ #include "mex.h" +//***************************************************************************** +// FUNCTION: mexFunction +//> The MATLAB Executable Gateway Function. +// +// @todo Describe this MEX function +// +// @param nlhs the number of left-hand side parameters. +// @param plhs the array of left-hand side parameters. +// @param nrhs the number of right-hand side parameters. +// @param prhs the array of right-hand side parameters. +//< +//***************************************************************************** void mexFunction( int nlhs, mxArray* plhs[], Index: Damkjer/Util/SpatialIndexing/Metrics/ChebyshevDistance.h =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/ChebyshevDistance.h (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/ChebyshevDistance.h (revision 12) @@ -4,15 +4,11 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: ChebyshevDistance -// This class describes a Chebyshev distance metric. Distances between two -// points, p and q, in n-dimensional Chebyshev space are calculated as -// follows: +// DESCRIPTION: +//> The public interface defintion for the Chebyshev distance metric functor. +//< // -// d(p,q)=max{i=0:n}(|p[i] - q[i]|). -// -// LIMITATIONS: ChebyshevDistance -// The ChebyshevDistance functor must operate on an STL container class, or -// a class that supports "duck" typing through a public typedef named -// "value_type". +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -27,9 +23,17 @@ //***************************************************************************** -#ifndef ChebyshevDistance_HEADER -#define ChebyshevDistance_HEADER +#ifndef Damkjer_ChebyshevDistance_HEADER +#define Damkjer_ChebyshevDistance_HEADER -#include -#include +#if _MSC_VER +#pragma warning(push, 0) +#endif + +#include // USES std::abs +#include // USES container const_iterator interface + +#if _MSC_VER +#pragma warning(pop) +#endif namespace Damkjer @@ -38,46 +42,101 @@ //***************************************************************************** // FUNCTOR: ChebyshevDistance +//> The Chebyshev distance metric. +// +// Distances between two points, x and y, in n-dimensional Chebyshev space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \max_{1 \le i \le n}\left(\left|x_{i}-y_{i}\right|\right) +// \f] +// +// @note +// The ChebyshevDistance functor must operate on an STL container class, or a +// class that supports "duck" typing through a public typedef named +// "value_type". +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +//< //***************************************************************************** -template +template class ChebyshevDistance { public: - typedef typename PointT value_type; - //> Add support for "duck" typing by publishing the point type for this - // functor. + + typedef PointT value_type; + //> The point type for this functor. //< - typedef typename ReturnT return_type; - //> Add support for "duck" typing by publishing the return type for this - // functor. + typedef ReturnT return_type; + //> The return type for this functor. //< - - //************************************************************************** - // ChebyshevDistance::operator() - //************************************************************************** - ReturnT operator()(const PointT& a, const PointT& b) const - { - // For predictable data fidelity, perform computations with the same - // fidelity as the point-type. - PointT::value_type temp, my_max = 0; - - for (typename PointT::const_iterator ai = a.begin(), bi = b.begin(); - ai != a.end() && bi != b.end(); - ++ai, ++bi) - { - temp = std::abs(*ai - *bi); - my_max = (temp > my_max) ? temp : my_max; - } - - // Then static-cast to the desired return type. - return static_cast(my_max); - } - //> The operator() function performs the distance calculation for - // Metrics functors. Distances between two points, p and q, in - // n-dimensional Chebyshev space are calculated as follows: - // - // d(p,q)=max{i=0:n}(|p[i] - q[i]|). + + //*** + // Use compiler-generated constructor, copy-constructor and destructor. + // ChebyshevDistance(); + // ChebyshevDistance(const ChebyshevDistance&); + // ~ChebyshevDistance(); + //*** + + //*** + // Use compiler-generated assignment operator. + // ChebyshevDistance& operator=(const ChebyshevDistance&); + //*** + + ReturnT operator()(const PointT&, const PointT&) const; + //> Perform the distance calculation. //< }; + +//***************************************************************************** +// ChebyshevDistance::operator()(const PointT&, const PointT&) +//> Perform the distance calculation. +// +// Distances between two points, x and y, in n-dimensional Chebyshev space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \max_{1 \le i \le n}\left(\left|x_{i}-y_{i}\right|\right) +// \f] +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +// @param x the first point. +// @param y the second point. +// @return the distance between the two argument points. +//< +//***************************************************************************** +template +inline ReturnT +ChebyshevDistance::operator()(const PointT& x, + const PointT& y) +const +{ + //*** + // For predictable data fidelity, perform computations with the same + // fidelity as the point-type. + //*** + typename PointT::value_type temp, my_max = 0; + + for (typename PointT::const_iterator xi = x.begin(), yi = y.begin(); + xi != x.end() && yi != y.end(); + ++xi, ++yi) + { + temp = std::abs(*xi - *yi); + my_max = (temp > my_max) ? temp : my_max; + } + + // Then static-cast to the desired return type. + return static_cast(my_max); +} } Index: Damkjer/Util/SpatialIndexing/Metrics/EuclideanDistance.h =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/EuclideanDistance.h (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/EuclideanDistance.h (revision 12) @@ -4,15 +4,11 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: EuclideanDistance -// This class describes a Euclidean distance metric. Distances between two -// points, p and q, in n-dimensional Euclidean space are calculated as -// follows: +// DESCRIPTION: +//> The public interface defintion for the Euclidean distance metric functor. +//< // -// d(p,q)=sqrt(sum{i=0:n}((p[i] - q[i])^2)). -// -// LIMITATIONS: EuclideanDistance -// The EuclideanDistance functor must operate on an STL container class, or -// a class that supports "duck" typing through a public typedef named -// "value_type". +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -27,9 +23,9 @@ //***************************************************************************** -#ifndef EuclideanDistance_HEADER -#define EuclideanDistance_HEADER +#ifndef Damkjer_EuclideanDistance_HEADER +#define Damkjer_EuclideanDistance_HEADER -#include -#include +#include // USES std::sqrt +#include // USES container const_iterator interface namespace Damkjer @@ -38,45 +34,99 @@ //***************************************************************************** // FUNCTOR: EuclideanDistance +//> The Euclidean distance metric. +// +// Distances between two points, x and y, in n-dimensional Euclidean space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \sqrt{\sum_{i=0}^{n}\left(x_{i}-y_{i}\right)^{2}} +// \f] +// +// @note +// The EuclideanDistance functor must operate on an STL container class, or a +// class that supports "duck" typing through a public typedef named +// "value_type". +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +//< //***************************************************************************** -template +template class EuclideanDistance { public: - typedef typename PointT value_type; - //> Add support for "duck" typing by publishing the point type for this - // functor. + typedef PointT value_type; + //> The point type for this functor. //< - typedef typename ReturnT return_type; - //> Add support for "duck" typing by publishing the return type for this - // functor. + typedef ReturnT return_type; + //> The return type for this functor. //< - - //************************************************************************** - // EuclideanDistance::operator() - //************************************************************************** - ReturnT operator()(const PointT& a, const PointT& b) const - { - // For predictable data fidelity, perform computations with the same - // fidelity as the point-type. - PointT::value_type sum = 0; - for (typename PointT::const_iterator ai = a.begin(), bi = b.begin(); - ai != a.end() && bi != b.end(); - ++ai, ++bi) - { - sum += (*ai - *bi) * (*ai - *bi); - } + //*** + // Use compiler-generated constructor, copy-constructor and destructor. + // EuclideanDistance(); + // EuclideanDistance(const EuclideanDistance&); + // ~EuclideanDistance(); + //*** - // Then static-cast to the desired return type. - return static_cast(std::sqrt(sum)); - } - //> The operator() function performs the distance calculation for - // Metrics functors. Distances between two points, p and q, in - // n-dimensional Euclidean space are calculated as follows: - // - // d(p,q)=sqrt(sum{i=0:n}((p[i] - q[i])^2)). + //*** + // Use compiler-generated assignment operator. + // EuclideanDistance& operator=(const EuclideanDistance&); + //*** + + ReturnT operator()(const PointT&, const PointT&) const; + //> Perform the distance calculation. //< }; + +//***************************************************************************** +// EuclideanDistance::operator()(const PointT&, const PointT&) +//> Perform the distance calculation. +// +// Distances between two points, x and y, in n-dimensional Euclidean space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \sqrt{\sum_{i=0}^{n}\left(x_{i}-y_{i}\right)^{2}} +// \f] +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +// @param x the first point. +// @param y the second point. +// @return the distance between the two argument points. +//< +//***************************************************************************** +template +inline ReturnT +EuclideanDistance::operator()(const PointT& x, + const PointT& y) +const +{ + //*** + // For predictable data fidelity, perform computations with the same + // fidelity as the point-type. + //*** + typename PointT::value_type sum = 0; + + for (typename PointT::const_iterator xi = x.begin(), yi = y.begin(); + xi != x.end() && yi != y.end(); + ++xi, ++yi) + { + sum += (*xi - *yi) * (*xi - *yi); + } + + // Then static-cast to the desired return type. + return static_cast(std::sqrt(sum)); +} } Index: Damkjer/Util/SpatialIndexing/Metrics/ManhattanDistance.h =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/ManhattanDistance.h (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/ManhattanDistance.h (revision 12) @@ -4,15 +4,11 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: ManhattanDistance -// This class describes a Manhattan distance metric. Distances between two -// points, p and q, in n-dimensional Manhattan space are calculated as -// follows: +// DESCRIPTION: +//> The public interface defintion for the Manhattan distance metric functor. +//< // -// d(p,q)=sum{i=0:n}(|p[i] - q[i]|). -// -// LIMITATIONS: ManhattanDistance -// The ManhattanDistance functor must operate on an STL container class, or -// a class that supports "duck" typing through a public typedef named -// "value_type". +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -27,9 +23,9 @@ //***************************************************************************** -#ifndef ManhattanDistance_HEADER -#define ManhattanDistance_HEADER +#ifndef Damkjer_ManhattanDistance_HEADER +#define Damkjer_ManhattanDistance_HEADER -#include -#include +#include // USES std::abs +#include // USES container const_iterator interface namespace Damkjer @@ -38,45 +34,99 @@ //***************************************************************************** // FUNCTOR: ManhattanDistance +//> The Manhattan distance metric. +// +// Distances between two points, x and y, in n-dimensional Manhattan space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \sum_{i=0}^{n}\left(\left|x_{i}-y_{i}\right|\right) +// \f] +// +// @note +// The ManhattanDistance functor must operate on an STL container class, or a +// class that supports "duck" typing through a public typedef named +// "value_type". +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +//< //***************************************************************************** -template +template class ManhattanDistance { public: - typedef typename PointT value_type; - //> Add support for "duck" typing by publishing the point type for this - // functor. + typedef PointT value_type; + //> The point type for this functor. //< - typedef typename ReturnT return_type; - //> Add support for "duck" typing by publishing the return type for this - // functor. + typedef ReturnT return_type; + //> The return type for this functor. //< - - //************************************************************************** - // ManhattanDistance::operator() - //************************************************************************** - ReturnT operator()(const PointT& a, const PointT& b) const - { - // For predictable data fidelity, perform computations with the same - // fidelity as the point-type. - PointT::value_type sum = 0; - - for (typename PointT::const_iterator ai = a.begin(), bi = b.begin(); - ai != a.end() && bi != b.end(); - ++ai, ++bi) - { - sum += std::abs(*ai - *bi); - } - - // Then static-cast to the desired return type. - return static_cast(sum); - } - //> The operator() function performs the distance calculation for - // Metrics functors. Distances between two points, p and q, in - // n-dimensional Manhattan space are calculated as follows: - // - // d(p,q)=sum{i=0:n}(|p[i] - q[i]|). + + //*** + // Use compiler-generated constructor, copy-constructor and destructor. + // ManhattanDistance(); + // ManhattanDistance(const ManhattanDistance&); + // ~ManhattanDistance(); + //*** + + //*** + // Use compiler-generated assignment operator. + // ManhattanDistance& operator=(const ManhattanDistance&); + //*** + + ReturnT operator()(const PointT&, const PointT&) const; + //> Perform the distance calculation. //< }; + +//***************************************************************************** +// ManhattanDistance::operator()(const PointT&, const PointT&) +//> Perform the distance calculation. +// +// Distances between two points, x and y, in n-dimensional Manhattan space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \sum_{i=0}^{n}\left(\left|x_{i}-y_{i}\right|\right) +// \f] +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +// @param x the first point. +// @param y the second point. +// @return the distance between the two argument points. +//< +//***************************************************************************** +template +inline ReturnT +ManhattanDistance::operator()(const PointT& x, + const PointT& y) +const +{ + //*** + // For predictable data fidelity, perform computations with the same + // fidelity as the point-type. + //*** + typename PointT::value_type sum = 0; + + for (typename PointT::const_iterator xi = x.begin(), yi = y.begin(); + xi != x.end() && yi != y.end(); + ++xi, ++yi) + { + sum += std::abs(*xi - *yi); + } + + // Then static-cast to the desired return type. + return static_cast(sum); +} } Index: Damkjer/Util/SpatialIndexing/Metrics/Metrics.h =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/Metrics.h (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/Metrics.h (revision 12) @@ -4,7 +4,11 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: This header is a convenience wrapper for metrics. +// DESCRIPTION: +//> A convenience inclusion wrapper for defined metrics. +//< // // LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -20,6 +24,6 @@ //***************************************************************************** -#ifndef Metrics_HEADER -#define Metrics_HEADER +#ifndef Damkjer_Metrics_HEADER +#define Damkjer_Metrics_HEADER #include "Util/SpatialIndexing/Metrics/EuclideanDistance.h" Index: Damkjer/Util/SpatialIndexing/Metrics/MinkowskiDistance.h =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/MinkowskiDistance.h (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/MinkowskiDistance.h (revision 12) @@ -4,16 +4,11 @@ // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: MinkowskiDistance -// This class describes a Minkowski distance metric. The Minkowski distance -// must be defined with a power parameter, p. Distances between two -// points, a and b, in n-dimensional Minkowski space are calculated as -// follows: -// -// d(a,b)=(sum{i=0:n}((a[i] - b[i])^p))^(1/p). -// -// LIMITATIONS: MinkowskiDistance -// The MinkowskiDistance functor must operate on an STL container class, or -// a class that supports "duck" typing through a public typedef named -// "value_type". +// DESCRIPTION: +//> The public interface defintion for the Minkowski distance metric functor. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -28,104 +23,184 @@ //***************************************************************************** -#ifndef MinkowskiDistance_HEADER -#define MinkowskiDistance_HEADER - -#include -#include - -#include "damkjerConfig.h" - -namespace Damkjer -{ +#ifndef Damkjer_MinkowskiDistance_HEADER +#define Damkjer_MinkowskiDistance_HEADER + +#include // USES std::abs and std::pow +#include // USES container const_iterator interface + +#include "Util/Exception/Exception.h" // USES Damkjer::DomainException interface + +namespace Damkjer { //***************************************************************************** // FUNCTOR: MinkowskiDistance -//***************************************************************************** -template +//> The Minkowski distance metric. +// +// Distances between two points, x and y, in n-dimensional Minkowski space are +// calculated as follows: +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \left(\sum_{i=0}^{n}\left(\left|x_{i}- +// y_{i}\right|\right)^{p}\right)^{\frac{1}{p}} +// \f] +// +// @note +// The MinkowskiDistance functor must operate on an STL container class, or a +// class that supports "duck" typing through a public typedef named +// "value_type". +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +//< +//***************************************************************************** +template class MinkowskiDistance { public: - typedef typename PointT value_type; - //> Add support for "duck" typing by publishing the point type for this - // functor. - //< - - typedef typename ReturnT return_type; - //> Add support for "duck" typing by publishing the return type for this - // functor. - //< - - //************************************************************************** - // MinkowskiDistance::MinkowskiDistance - //************************************************************************** - MinkowskiDistance() - : theP(static_cast(2)) + + explicit MinkowskiDistance(typename PointT::value_type p = Euclidean); + //> Intialize the Minkowski distance metric with a power value. + //< + + //*** + // Use compiler-generated copy-constructor and destructor + // MinkowskiDistance(const MinkowskiDistance&); + // ~MinkowskiDistance(const MinkowskiDistance&); + //*** + + //*** + // Use compiler-generated assignment operator. + // MinkowskiDistance& operator=(const MinkowskiDistance&); + //*** + + ReturnT operator()(const PointT& a, const PointT& b) const; + //> Perform the distance calculation. + //< + + typedef PointT value_type; + //> The point type for this functor. + //< + + typedef ReturnT return_type; + //> The return type for this functor. + //< + +private: + //*** + // ENUMERATION: Special + //> List of pre-defined Minkowski metrics. + //< + //*** + enum Special { + Manhattan = 1, //> Manhattan distance is defined when p == 1. + //< + Euclidean = 2 //> Euclidean distance is defined when p == 2. + //< + }; + + typename PointT::value_type thePower; + //> The power value. + //< +}; + +//***************************************************************************** +// MinkowskiDistance::MinkowskiDistance(PointT::value_type) +//> Intialize the Minkowski distance metric with a power value. +// +// This constructor is the default constructor if no arguments are provided. +// The default power value creates a Euclidean metric (p = 2). +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +// @param p the power value. Default to Euclidean (2). +// @throw DomainError when p < 1. +//< +//***************************************************************************** +template +MinkowskiDistance::MinkowskiDistance( + typename PointT::value_type p) + : thePower(p) +{ + EXCEPTION_TRY("Damkjer::MinkowskiDistance::" + "MinkowskiDistance"); + + if (thePower < 1) + { + //*** + // In released code, there's not a whole lot that the user can do + // about this problem. This is a logic error and should be prevented + // through appropriate bounds checking on the input prior to + // calling the constructor. + //*** + std::ostringstream msg; + + msg << "Error encountered while defining a Minkowski distance " + << "metric.\n\n" + << "Unable to define a Minkowski distance metric with the " + << "requested p-value: " << thePower << ". The Minkowski distance " + << "must be defined with p >= 1 to describe a metric space."; + + throw DomainError(msg.str(), MODULE, __FILE__, __LINE__); } - //************************************************************************** - // MinkowskiDistance::MinkowskiDistance - //************************************************************************** - explicit MinkowskiDistance(typename PointT::value_type p) - : theP(static_cast(p)) + EXCEPTION_RETHROW; +} + +//***************************************************************************** +// MinkowskiDistance::operator()(const PointT&, const PointT&) +//> Perform the distance calculation. +// +// Distances between two points, x and y, in n-dimensional Minkowski space are +// calculated as follows: +// +// +// +// +// +// \f[ +// d\left(\bm{x},\bm{y}\right)= +// \left(\sum_{i=0}^{n}\left(\left|x_{i}- +// y_{i}\right|\right)^{p}\right)^{\frac{1}{p}} +// \f] +// +// @tparam PointT the point type. +// @tparam ReturnT the return type. +// @param x the first point. +// @param y the second point. +// @return the distance between the two argument points. +//< +//***************************************************************************** +template +inline ReturnT +MinkowskiDistance::operator()(const PointT& x, + const PointT& y) +const +{ + //*** + // For predictable data fidelity, perform computations with the same + // fidelity as the point-type. + //*** + typename PointT::value_type sum = 0; + + for (typename PointT::const_iterator xi = x.begin(), yi = y.begin(); + xi != x.end() && yi != y.end(); + ++xi, ++yi) { - EXCEPTION_TRY("Damkjer::MinkowskiDistance::" - "MinkowskiDistance"); - - if (theP < 1) - { - //*** - // In released code, there's not a whole lot that the user can do - // about this problem. This is a logic error and should be prevented - // through appropriate bounds checking on the input prior to - // calling the constructor. - //*** - std::ostringstream msg; - - msg << "Error encountered while defining a Minkowski distance " - << "metric.\n\n" - << "Unable to define a Minkowski distance metric with the " - << "requested p-value: " << theP << ". The Minkowski distance " - << "must be defined with p >= 1 to describe a metric space."; - - throw DomainError(msg.str(), MODULE, __FILE__, __LINE__); - } - - EXCEPTION_RETHROW; + sum += std::pow(std::abs(*xi - *yi), thePower); } - //************************************************************************** - // MinkowskiDistance::operator() - //************************************************************************** - ReturnT operator()(const PointT& a, const PointT& b) const - { - // For predictable data fidelity, perform computations with the same - // fidelity as the point-type. - PointT::value_type sum = 0; - - for (typename PointT::const_iterator ai = a.begin(), bi = b.begin(); - ai != a.end() && bi != b.end(); - ++ai, ++bi) - { - sum += std::pow(std::abs(*ai - *bi), theP); - } - - // Then static-cast to the desired return type. - static const typename PointT::value_type ONE = - static_cast(1.); - return static_cast(std::pow(sum, ONE/theP)); - } - //> The operator() function performs the distance calculation for - // Metrics functors. Distances between two points, p and q, in - // n-dimensional Minkowski space are calculated as follows: - // - // d(a,b)=(sum{i=0:n}((a[i] - b[i])^p))^(1/p). - //< - -protected: - typename PointT::value_type theP; -}; - + // Then static-cast to the desired return type. + static const typename PointT::value_type ONE = + static_cast(1.); + + return static_cast(std::pow(sum, ONE/thePower)); } +} + #endif Index: Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.cpp =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.cpp (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.cpp (revision 12) @@ -23,6 +23,6 @@ #include -#include "damkjerConfig.h" #include "TestMetrics.h" +#include "Util/Exception/Exception.h" #include "Util/SpatialIndexing/Metrics/Metrics.h" #include "Util/Streams/BlockIndent.h" @@ -67,11 +67,13 @@ EXCEPTION_TRY("Damkjer::testEuclidean::operator(TestCase&)"); + typedef typename PointT::value_type ValueT; + PointT a; - a.push_back(static_cast(0.3)); - a.push_back(static_cast(0.5)); + a.push_back(static_cast(0.3)); + a.push_back(static_cast(0.5)); PointT b; - b.push_back(static_cast(0.7)); - b.push_back(static_cast(0.8)); + b.push_back(static_cast(0.7)); + b.push_back(static_cast(0.8)); ReturnT fromMetric = theMetric(a, b); @@ -84,11 +86,16 @@ // 0.5 //*** - bool passed = - approx_equal(fromMetric, static_cast(0.5), - std::numeric_limits::epsilon()); - - test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" + double valTol = std::numeric_limits::epsilon(); + double retTol = std::numeric_limits::epsilon(); + + double tol = (valTol > retTol) ? valTol : retTol; + + bool passed = approx_equal(fromMetric, static_cast(0.5), tol); + + test.report() << "Value from Euclidean Metric: " + << std::setprecision(12) << fromMetric << "\n" << "Expected result : " - << std::setprecision(12) << static_cast(0.5) << "\n"; + << std::setprecision(12) << static_cast(0.5) + << "\n"; return passed; @@ -122,33 +129,17 @@ //< - bool approx_equal(ReturnT a, ReturnT b) const - { - double absTolI = std::numeric_limits::epsilon(); - double absTolO = std::numeric_limits::epsilon(); - - double absTol = (absTolI > absTolO) ? absTolI : absTolO; - - ReturnT inMax = (std::abs(a) > std::abs(b)) - ? std::abs(a) - : std::abs(b); - - inMax = (inMax > static_cast(1.0)) - ? inMax - : static_cast(1.0); - - return (std::abs(a - b) <= absTol * inMax); - } - bool operator()(TestCase& test) const { EXCEPTION_TRY("Damkjer::testManhattan::operator(TestCase&)"); + typedef typename PointT::value_type ValueT; + PointT a; - a.push_back(static_cast(0.3)); - a.push_back(static_cast(0.5)); + a.push_back(static_cast(0.3)); + a.push_back(static_cast(0.5)); PointT b; - b.push_back(static_cast(0.7)); - b.push_back(static_cast(0.8)); + b.push_back(static_cast(0.7)); + b.push_back(static_cast(0.8)); ReturnT fromMetric = theMetric(a, b); @@ -159,9 +150,16 @@ // 0.7 //*** - bool passed = approx_equal(fromMetric, static_cast(0.7)); - - test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" + double valTol = std::numeric_limits::epsilon(); + double retTol = std::numeric_limits::epsilon(); + + double tol = (valTol > retTol) ? valTol : retTol; + + bool passed = approx_equal(fromMetric, static_cast(0.7), tol); + + test.report() << "Value from Euclidean Metric: " + << std::setprecision(12) << fromMetric << "\n" << "Expected result : " - << std::setprecision(12) << static_cast(0.7) << "\n"; + << std::setprecision(12) << static_cast(0.7) + << "\n"; return passed; @@ -195,33 +193,17 @@ //< - bool approx_equal(ReturnT a, ReturnT b) const - { - double absTolI = std::numeric_limits::epsilon(); - double absTolO = std::numeric_limits::epsilon(); - - double absTol = (absTolI > absTolO) ? absTolI : absTolO; - - ReturnT inMax = (std::abs(a) > std::abs(b)) - ? std::abs(a) - : std::abs(b); - - inMax = (inMax > static_cast(1.0)) - ? inMax - : static_cast(1.0); - - return (std::abs(a - b) <= absTol * inMax); - } - bool operator()(TestCase& test) const { EXCEPTION_TRY("Damkjer::testChebyshev::operator(TestCase&)"); + typedef typename PointT::value_type ValueT; + PointT a; - a.push_back(static_cast(0.3)); - a.push_back(static_cast(0.5)); + a.push_back(static_cast(0.3)); + a.push_back(static_cast(0.5)); PointT b; - b.push_back(static_cast(0.7)); - b.push_back(static_cast(0.8)); + b.push_back(static_cast(0.7)); + b.push_back(static_cast(0.8)); ReturnT fromMetric = theMetric(a, b); @@ -232,9 +214,16 @@ // 0.4 //*** - bool passed = approx_equal(fromMetric, static_cast(0.4)); - - test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" + double valTol = std::numeric_limits::epsilon(); + double retTol = std::numeric_limits::epsilon(); + + double tol = (valTol > retTol) ? valTol : retTol; + + bool passed = approx_equal(fromMetric, static_cast(0.4), tol); + + test.report() << "Value from Euclidean Metric: " + << std::setprecision(12) << fromMetric << "\n" << "Expected result : " - << std::setprecision(12) << static_cast(0.4) << "\n"; + << std::setprecision(12) << static_cast(0.4) + << "\n"; return passed; @@ -268,35 +257,17 @@ //< - bool approx_equal(ReturnT a, ReturnT b) const - { - double absTolI = std::numeric_limits::epsilon(); - double absTolO = std::numeric_limits::epsilon(); - - double absTol = (absTolI > absTolO) ? absTolI : absTolO; - - ReturnT inMax = (std::abs(a) > std::abs(b)) - ? std::abs(a) - : std::abs(b); - - inMax = (inMax > static_cast(1.0)) - ? inMax - : static_cast(1.0); - - return (std::abs(a - b) <= absTol * inMax); - } - //> - //< - bool operator()(TestCase& test) const { EXCEPTION_TRY("Damkjer::testMinkowski::operator(TestCase&)"); + typedef typename PointT::value_type ValueT; + PointT a; - a.push_back(static_cast(0.3)); - a.push_back(static_cast(0.5)); + a.push_back(static_cast(0.3)); + a.push_back(static_cast(0.5)); PointT b; - b.push_back(static_cast(0.7)); - b.push_back(static_cast(0.8)); + b.push_back(static_cast(0.7)); + b.push_back(static_cast(0.8)); ReturnT fromMetric = theMetric(a, b); @@ -309,9 +280,16 @@ // 0.5 //*** - bool passed = approx_equal(fromMetric, static_cast(0.5)); - - test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" + double valTol = std::numeric_limits::epsilon(); + double retTol = std::numeric_limits::epsilon(); + + double tol = (valTol > retTol) ? valTol : retTol; + + bool passed = approx_equal(fromMetric, static_cast(0.5), tol); + + test.report() << "Value from Euclidean Metric: " + << std::setprecision(12) << fromMetric << "\n" << "Expected result : " - << std::setprecision(12) << static_cast(0.5) << "\n"; + << std::setprecision(12) << static_cast(0.5) + << "\n"; return passed; @@ -339,6 +317,7 @@ minkowskiThrow() : TestCase::TestStep( - std::string("throw from ")+ - std::string(typeid(MinkowskiDistance).name())) + std::string("throw from ") + +// std::string(typeid(MinkowskiDistance).name())) + std::string(typeid(this).name())) { } @@ -364,5 +343,5 @@ test.report() << "Caught expected exception:\n"; - test.report() << blockIndent() << e; + test.report() << BlockIndent() << e; e.stackTrace(test.report()); test.report() << endBlock; Index: Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.h =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.h (revision 9) +++ Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.h (revision 12) @@ -29,4 +29,7 @@ //> //< +private: + TestMetrics(const TestMetrics&); + TestMetrics& operator=(const TestMetrics&); }; Index: Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.vcxproj =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.vcxproj (revision 10) +++ Damkjer/Util/SpatialIndexing/Metrics/test/TestMetrics.vcxproj (revision 12) @@ -2,4 +2,12 @@ + + DebugOMP + Win32 + + + DebugOMP + x64 + Debug @@ -48,5 +56,13 @@ true + + Application + true + + Application + true + + Application true @@ -74,5 +90,11 @@ + + + + + + @@ -95,5 +117,14 @@ call $(TargetPath) + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + call $(TargetPath) + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ @@ -132,4 +163,22 @@ Console + + + + + _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + Console + setlocal @@ -171,4 +220,21 @@ Console + + + + + _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + Console + setlocal @@ -244,4 +310,7 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) true + AnySuitable + true + Speed @@ -326,4 +395,8 @@ true Level4 + /wd4514 /wd4571 /wd4668 /wd4710 /wd4711 /wd4820 /wd4986 %(AdditionalOptions) + AnySuitable + true + Speed Index: Damkjer/Util/SpatialIndexing/Metrics/test/test_Metrics.cpp =================================================================== --- Damkjer/Util/SpatialIndexing/Metrics/test/test_Metrics.cpp (revision 9) +++ Damkjer/Util/SpatialIndexing/Metrics/test/test_Metrics.cpp (revision 12) @@ -14,5 +14,5 @@ //***************************************************************************** -#include "damkjerConfig.h" +#include "Util/Exception/Exception.h" #include "TestMetrics.h" Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree.h (revision 10) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree.h (revision 12) @@ -1,12 +1,55 @@ -//***************************************************************************** +//**************************************************************************** // FILE: VpTree.h // // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: VpTree +// DESCRIPTION: +//> The interface definition for vantage-point trees. +//< +// +// LIMITATIONS: +//> This class template file follows the template inclusion pattern. This +// header file should be the only file included by clients wishing to +// instantiate a VpTree specialization. +//< +// +// SOFTWARE HISTORY: +// +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//**************************************************************************** +#ifndef Damkjer_VpTree_HEADER +#define Damkjer_VpTree_HEADER + +#if _OPENMP +#include // USES OpenMP pragmas +#endif + +#include // USES std::size_t for index type. +#include // USES std::vector interface for default point type. +#include // USES std::deque interface for search results. +#include // USES std::set interface for random sampling. +#include // USES std::priority_queue interface for search results. +#include // USES std::numeric_limits to establish default reach. + +// USES Euclidean metric as default search space. +#include "Util/SpatialIndexing/Metrics/EuclideanDistance.h" + +namespace Damkjer +{ + +//***************************************************************************** +// CLASS: VpTree +//> A vantage point tree data structure and related search algorithms. // // This class is an implementation of the vantage point tree data structure // described by Peter Yianilos in "Data Structures and Algorithms for -// Nearest Neighbor Search in General Metric Spaces". +// Nearest Neighbor Search in General Metric Spaces". @cite Yianilos:1993 // // This structure includes the enhancement to collapse subtrees near leaves @@ -15,9 +58,8 @@ // is chosen to be too large. // -// LIMITATIONS: -// +// @note // The tree is currently coded as VPsb tree to attempt to realize the best // balance in construct and search performance. -// +// @note // Code was developed and analyzed to determine the benefit of enhancing // the vantage point selection process. Extra effort was spent on finding a @@ -27,15 +69,15 @@ // queries as tree coverage increases. However, in practice, the vantage // point selection seemed to have marginal, if any, effect on query time. -// +// @note // The tree includes the enhancement to track tight bounds on the branch // sub-spaces. For a slight storage overhead, we track the tight lower and // upper bounds for each branch which allows for earlier pruning of // branches at the cost of slightly increased storage and construct time. -// +// @note // The tree also includes the enhancement to track distances to ancestral // pivots. This change potentially incurs a signficant storage overhead, // but allows for further explicit pruning or inclusion optimizations for // range queries. -// +// @note // A final proposed enhancement would be to increase fan-out of the tree by // establishing multiple partition boundaries, or by modifying the @@ -43,63 +85,51 @@ // really talking about a different data structure. // -// SOFTWARE HISTORY: -// -//> 2012-SEP-11 K. Damkjer -// Initial Coding. -// 2013-JUL-23 K. Damkjer -// Set typedefs to make code more readable and to allow for -// varying container and metric types. This is useful when the -// default double-precision is overkill. It is now easy to set -// types to float. -//< -//***************************************************************************** - -#ifndef VpTree_HEADER -#define VpTree_HEADER - -#include -#include -#include -#include -#include - -#include "damkjerConfig.h" -#include "Util/SpatialIndexing/Metrics/Metrics.h" - -namespace Damkjer -{ - -//***************************************************************************** -// CLASS: VpTree -//***************************************************************************** - -EXPORT template > > +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template > > class VpTree { public: - typedef typename MetricT::value_type PointT; + typedef typename MetricT::value_type PointT; + //> The point record type, derived from the metric value type. + //< + + typedef typename PointT::difference_type DiffT; + //> The difference type, derived from the point record difference type. + //< + typedef typename MetricT::return_type DistT; - typedef std::size_t IndexT; + //> The distance type, derived from the metric return type. + //< + + typedef std::size_t IndexT; + //> The index type, consistent with STL size type. + //< + typedef std::pair, std::deque > SearchResultsT; - - VpTree(const MetricT& metric=MetricT(), - const IndexT& leafCapacity=8); - //> The default constructor creates a null tree. + //> The search results type, a pair of deques of indices and distances. + //< + + explicit VpTree(const MetricT& metric=MetricT(), + const IndexT& leafCapacity=8); + //> Instantiate an empty tree. //< template - VpTree(const DatabaseT&, - const MetricT& metric=MetricT(), - const IndexT& leafCapacity=8); - //> Create a VpTree from a (probably unsorted) database of items. + explicit VpTree(const DatabaseT&, + const MetricT& metric=MetricT(), + const IndexT& leafCapacity=8); + //> Instantiate a tree from a database of items. //< virtual ~VpTree(); - //> Free resources allocated by this tree. + //> Destruct the tree and deallocate resources. //< SearchResultsT knn(const PointT&, const IndexT&, - const DistT& limit=std::numeric_limits::max()) const; + const DistT& limit=std::numeric_limits::max()) + const; //> Perform a k nearest neighbor search on the tree returning the // indices of and distances to the k nearest neighbors. @@ -113,41 +143,38 @@ private: + + // Make the node types inner classes. + class Node; + //> An abstract node interface for a vantage point tree. + //< + + class Branch; + //> A vantage-point tree internal (non-terminal) node. + //< + + class Leaf; + //> A vantage-point tree terminal node. + //< + + // Perform item management with inner classes as well. + class Item; + //> A simple container to capture a database element along with its index + // and ancestral pivot history. + //< + + class ResultsCandidate; + //> A light-weight representation of a search result candidate item. + //< + + typedef std::priority_queue ResultsSetT; + //> Search results are built by traversing the vantage point tree and + // maintaining candidate results on a priority queue sorted by distance + // to the query. + //< + VpTree(const VpTree&); - //> Disable copy construction for VpTree. - //< - - class Item; - //> The VpsTree::Item class provides a simple container to capture a - // database element along with its index and ancestral pivot - // history. - //< - - class ResultsCandidate; - //> The VpTree::ResultsCandidate class provides a private - // representation of search result candidates to be employed in an - // intermediate priority queue of candidate results. - //< - - typedef std::priority_queue ResultsSetT; - - class Node; - //> The VpTree::Node class provides the private definition of - // general VpTree nodes. - //< - - class Internal; - //> The VpTree::Internal class provides the private definition of - // internal VpTree nodes. - //< - - class Leaf; - //> The VpTree::Node class provides the private definition of - // VpTree leaf nodes. - //< - - // All of the node-types need access to "theItems". - friend class VpTree::Node; - friend class VpTree::Internal; - friend class VpTree::Leaf; + //> Explicitly disable the compiler-generated copy constructor. No + // definition provided. + //< Node* makeTree(const IndexT&, const IndexT&); @@ -156,20 +183,20 @@ //< + std::set randomSample(const IndexT&, const IndexT&) const; + //> Select a random sample in the range between the provided indices. + //< + IndexT selectVp(const IndexT&, const IndexT&) const; //> Select a vantage point in the range between the provided indices. //< - std::set randomSample(const IndexT&, const IndexT&) const; - //> Select a random sample in the range between the provided indices. - //< - Node* theRoot; - //> The VpTree root is the starting point for all queries against the - // database represented by the VpTree. + //> The root is the starting point for all queries against the database + // represented by the VpTree. //< std::deque theItems; - //> The items are the set of metric-space elements managed by the - // VpTree paired with their original indices in the unordered + //> The items are the set of metric-space elements managed by the vantage + // point tree paired with their original indices in the unordered // database. //< @@ -186,11 +213,116 @@ //> The distance metric used to construct and search this tree. //< + + friend class VpTree::Node; + //> There is a defect in the C++03 standard that forces friendship of + // nested classes to be explicitly declared. This relationship will be + // made implicit in C++11. + //< + + friend class VpTree::Branch; + //> There is a defect in the C++03 standard that forces friendship of + // nested classes to be explicitly declared. This relationship will be + // made implicit in C++11. + //< + + friend class VpTree::Leaf; + //> There is a defect in the C++03 standard that forces friendship of + // nested classes to be explicitly declared. This relationship will be + // made implicit in C++11. + //< }; +//***************************************************************************** +// VpTree::VpTree(const MetricT&, const IndexT&) +//> Instantiate an empty tree. +// +// @tparam MetricT The metric search space. +// @param metric The metric space to use for this tree's spatial +// index. +// @param leafCapacity The number of nodes to collapse into a single leaf. +//< +//***************************************************************************** +template +inline +VpTree::VpTree(const MetricT& metric, + const IndexT& leafCapacity) + : theRoot(0) + , theItems() + , theLeafCapacity((leafCapacity<1)?1:leafCapacity) + , theMetric(metric) +{ } -#if MAKE_DEPENDING || TEMPLATE_INCLUSION -#include "VpTree.hpp" +//***************************************************************************** +// VpTree::VpTree(const DatabaseT&, const MetricT&, const IndexT&) +//> Instantiate a tree from a database of items. +// +// @tparam MetricT The metric search space. +// @param elems The container of elements to be indexed. +// @param metric The metric space to use for this tree's spatial +// index. +// @param leafCapacity The number of nodes to collapse into a single leaf. +//< +//***************************************************************************** +template +template +inline +VpTree::VpTree(const DatabaseT& elems, + const MetricT& metric, + const IndexT& leafCapacity) + : theRoot(0) + , theItems(elems.size()) + , theLeafCapacity((leafCapacity<1)?1:leafCapacity) + , theMetric(metric) +{ + #if _OPENMP + if (omp_get_num_threads() == 1) + { + omp_set_dynamic(1); + omp_set_num_threads(omp_get_num_procs()); + } + #endif + + #pragma omp parallel for + for (int i = 0; i < static_cast(theItems.size()); ++i) + { + unsigned int idx = static_cast(i); + theItems[idx].theIndex=idx; + theItems[idx].theElement=elems[idx]; + } + + theRoot = makeTree(0, theItems.size()); +} + +//***************************************************************************** +// VpTree::~VpTree() +//> Destruct the tree and deallocate resources. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::~VpTree() +{ + delete theRoot; + theRoot = 0; +} + +} + +//***************************************************************************** +// External References +//***************************************************************************** +#include "VpTree_Node.h" +#include "VpTree_Branch.h" +#include "VpTree_Leaf.h" +#include "VpTree_Item.h" +#include "VpTree_ResultsCandidate.h" + +//***************************************************************************** +// Template Inclusion +//***************************************************************************** +#include "VpTree.hpp" // HASA VpTree Template Implementation. + #endif - -#endif Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree.hpp =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree.hpp (revision 10) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree.hpp (revision 12) @@ -1,13 +1,15 @@ //***************************************************************************** -// FILE: VpTree.cpp +// FILE: VpTree.hpp // // Copyright (C) 2012 Kristian Damkjer. // -// DESCRIPTION: This class is an implementation of the vantage point tree -// data structure described by Peter Yianilos in "Data -// Structures and Algorithms for Nearest Neighbor Search in -// General Metric Spaces". -// -// LIMITATIONS: See VpTree.h for full list of limitations. +// DESCRIPTION: +//> The template implementation for vantage-point trees. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< // // SOFTWARE HISTORY: @@ -26,427 +28,220 @@ #endif -#include "VpTree.h" - #include #include +#include "VpTree.h" + namespace Damkjer { //***************************************************************************** -// CLASS: VpTree::Node +// VpTree::knn(const PointT&, const IndexT&, const DistT&) +//> Perform a k nearest neighbor search on the tree returning the indices of +// and distances to the k nearest neighbors. +// +// @tparam MetricT The metric search space. +// @param query The query point to focus the search about. +// @param k The number of neighbors to identify. +// @param limit The radial reach used to bound the search. +// @return The search results ordered by distance to the query. +//< //***************************************************************************** template -class VpTree::Node -{ -public: - Node(); - //> The default constructor creates a null node. - //< - - Node(VpTree*); - //> Construct with a database reference. - //< - - virtual ~Node(); - //> The default destructor. Virtual to ensure proper Node - // destruction. - //< - - virtual void knn(const PointT&, - const IndexT&, - ResultsSetT&, - DistT&) const = 0; - //> The visitor that accumulates k nearest neighbor results. - //< - - virtual void rnn(const PointT&, - const DistT&, - ResultsSetT&) const = 0; - //> The visitor that accumulates fixed-radius nearest neighbor - // results. - //< - -protected: - VpTree* theTree; - //> The tree that this node belongs to. Included to avoid reallocating - // contained element data for each node. As a side effect, nodes - // organize the tree's data contents through the construction process. - // - // I personally debated including this pointer for quite a while since - // it seemed like a bad design to have such a cyclic reference in a tree - // structure, but it appears to be quite beneficial from a performance - // perspective. - //< -}; - -//***************************************************************************** -// CLASS: VpTree::Internal +typename VpTree::SearchResultsT +VpTree::knn(const PointT& query, + const IndexT& k, + const DistT& limit) +const +{ + ResultsSetT candidates; + DistT tau = limit; + + theRoot->knn(query, k, candidates, tau); + + std::deque indices; + std::deque distances; + + while(!candidates.empty()) + { + indices.push_back(theItems[candidates.top().theIndex].theIndex); + distances.push_back(candidates.top().theDistance); + candidates.pop(); + } + + std::reverse(indices.begin(), indices.end()); + std::reverse(distances.begin(), distances.end()); + + return std::make_pair(indices, distances); +} + +//***************************************************************************** +// VpTree::rnn(const PointT&, const DistT&) +//> Perform a fixed radius nearest neighbor search on the tree returning the +// indices of and distances to the neighbors in the fixed radius. +// +// @tparam MetricT The metric search space. +// @param query The query point to focus the search about. +// @param range The radial distance used to bound the search. +// @return The search results ordered by distance to the query. +//< //***************************************************************************** template -class VpTree::Internal : public VpTree::Node -{ -public: - Internal(); - //> The default constructor creates a null internal node. - //< - - Internal(VpTree*); - //> Construct with a database reference. - //< - - virtual ~Internal(); - //> The default destructor. Virtual to ensure proper Node - // destruction. - //< - - IndexT theIndex; - //> The index of the item in the internal database. - //< - - DistT theInnerLowerBound; - //> The lower bound distance to elements on inner branch. - //< - - DistT theInnerUpperBound; - //> The uuper bound distance to elements on inner branch. - //< - - DistT theOuterLowerBound; - //> The lower bound distance to elements on outer branch. - //< - - DistT theOuterUpperBound; - //> The upper bound distance to elements on outer branch. - //< - - Node* theInnerBranch; - //> The inner branch partition containing elements closer than - // theMedianPartition to this element. - //< - - Node* theOuterBranch; - //> The outer branch partition containing elements at or beyond - // theMedianPartition from this element. - //< - - virtual void knn(const PointT&, - const IndexT&, - ResultsSetT&, - DistT&) const; - //> The visitor that accumulates k nearest neighbor results. - //< - - virtual void rnn(const PointT&, - const DistT&, - ResultsSetT&) const; - //> The visitor that accumulates fixed radius nearest neighbor - // results. - //< -}; - -//***************************************************************************** -// CLASS: VpTree::Leaf +typename VpTree::SearchResultsT +VpTree::rnn(const PointT& query, + const DistT& range) +const +{ + ResultsSetT candidates; + + theRoot->rnn(query, range, candidates); + + std::deque indices; + std::deque distances; + + while(!candidates.empty()) + { + indices.push_back(theItems[candidates.top().theIndex].theIndex); + distances.push_back(candidates.top().theDistance); + candidates.pop(); + } + + std::reverse(indices.begin(), indices.end()); + std::reverse(distances.begin(), distances.end()); + + return std::make_pair(indices, distances); +} + +//***************************************************************************** +// VpTree::makeTree(const IndexT&, const IndexT&) +//> Set this tree's root to be the root of the tree created from the argument +// set of metric-space elements. +// +// @tparam MetricT The metric search space. +// @param start The beginning of the element range to transform into a +// binary tree. +// @param stop The end of the element range to transform into a binary +// tree. +// @return The root of the constructed tree. +//< //***************************************************************************** template -class VpTree::Leaf : public VpTree::Node -{ -public: - Leaf(); - //> The default constructor creates a null leaf. - //< - - Leaf(VpTree*, const IndexT&, const IndexT&); - //> Construct a leaf representing the items in the provided index - // range. - //< - - virtual ~Leaf(){} - //> The default destructor. Virtual to ensure proper Node - // destruction. - //< - - virtual void knn(const PointT&, - const IndexT&, - ResultsSetT&, - DistT&) const; - //> The visitor that accumulates k nearest neighbor results. - //< - - virtual void rnn(const PointT&, - const DistT&, - ResultsSetT&) const; - //> The visitor that accumulates fixed radius nearest neighbor - // results. - //< - -private: - IndexT theHead; - //> The start of the index range prepresented by this Leaf. - //< - - IndexT theTail; - //> The end of the index range prepresented by this Leaf. - //< -}; - -//***************************************************************************** -// CLASS: VpTree::Item -//***************************************************************************** -template -class VpTree::Item -{ -public: - Item(); - //> The default constructor creates a null node. - //< - - ~Item(){} - //> The default destructor. Intentionally non-virtual since Node is - // a private inner class on VpTree. - //< - - bool operator<(const Item&) const; - //> - //< - - IndexT theIndex; - //> The index of the item in the input data set. - //< - - PointT theElement; - //> The database object - //< - - DistT theDistance; - //> The most recent ancestral pivot history distance for this item. - //< -}; - -//***************************************************************************** -// VpTree::ResultsCandidate -//***************************************************************************** -template -class VpTree::ResultsCandidate -{ -public: - ResultsCandidate(const IndexT&, const DistT&); - //> Create a metric comparitor. - //< - - ~ResultsCandidate(){} - //> The default destructor. Intentionally non-virtual since - // ResultsCandidate is a private inner class on VpTree. - //< - - bool operator<(const ResultsCandidate&) const; - //> Compare result candidate distances to determine which is closer - // to the query. - //< - - IndexT theIndex; - //> The index of the candidate in the internal database. - //< - - DistT theDistance; - //> The candidate's distance to the query point. - //< -}; - -//***************************************************************************** -// VpTree::VpTree -//***************************************************************************** -template -inline VpTree::VpTree(const MetricT& metric, - const IndexT& leafCapacity) - : theRoot(0) - , theItems() - , theLeafCapacity((leafCapacity<1)?1:leafCapacity) - , theMetric(metric) -{ -} - -//***************************************************************************** -// VpTree::VpTree -//***************************************************************************** -template -template -inline VpTree::VpTree(const DatabaseT& elems, - const MetricT& metric, - const IndexT& leafCapacity) - : theRoot(0) - , theItems(elems.size()) - , theLeafCapacity((leafCapacity<1)?1:leafCapacity) - , theMetric(metric) -{ +typename VpTree::Node* +VpTree::makeTree(const IndexT& start, + const IndexT& stop) +{ + if (stop <= start) return 0; + + IndexT setSize = stop - start; + + if (setSize <= theLeafCapacity) + { + return new Leaf(this, start, stop); + } + + Branch* node=new Branch(this); + node->theIndex=start; + + const IndexT vp = selectVp(start, stop); + std::swap(theItems[start], theItems[vp]); + + // Identify bound elements + IndexT outerLowerBound = (start + stop + 1)/2; + IndexT innerLowerBound = start + 1; + + // Update histories + DistT d_max=0; + DistT d_min=std::numeric_limits::max(); + + for (IndexT elem = stop; elem --> innerLowerBound; ) + { + theItems[elem].theDistance = theMetric(theItems[start].theElement, + theItems[elem].theElement); + d_max = (theItems[elem].theDistance > d_max) + ? theItems[elem].theDistance : d_max; + d_min = (theItems[elem].theDistance < d_min) + ? theItems[elem].theDistance : d_min; + } + + // Put the median element in place + std::nth_element(theItems.begin() + static_cast(innerLowerBound), + theItems.begin() + static_cast(outerLowerBound), + theItems.begin() + static_cast(stop)); + + DistT d_mid=0; + + for (IndexT elem = outerLowerBound; elem --> innerLowerBound; ) + { + d_mid = (theItems[elem].theDistance > d_mid) + ? theItems[elem].theDistance : d_mid; + } + + node->theInnerLowerBound=d_min; + node->theInnerUpperBound=d_mid; + node->theOuterLowerBound=theItems[outerLowerBound].theDistance; + node->theOuterUpperBound=d_max; + #if _OPENMP - omp_set_dynamic(1); - omp_set_num_threads(omp_get_num_procs()); + static int threads = 0; + + if (threads < (omp_get_num_procs()-1)) + { + if (omp_get_num_threads() == 1) + { + omp_set_dynamic(1); + omp_set_num_threads(omp_get_num_procs()); + } + + if (!omp_get_nested()) + { + omp_set_nested(1); + } + + #pragma omp atomic + ++threads; + + #pragma omp parallel + { + #pragma omp sections nowait + { + node->theInnerBranch = makeTree(innerLowerBound, + outerLowerBound); + + #pragma omp section + node->theOuterBranch = makeTree(outerLowerBound, stop); + } + } + + #pragma omp atomic + --threads; + } + else #endif - - #pragma omp parallel for - for (int i = 0; i < theItems.size(); ++i) - { - theItems[i].theIndex=i; - theItems[i].theElement=elems[i]; - } - - theRoot = makeTree(0, theItems.size()); -} - -//***************************************************************************** -// VpTree::~VpTree -//***************************************************************************** -template -inline VpTree::~VpTree() -{ - delete theRoot; - theRoot = 0; -} - -//***************************************************************************** -// VpTree::Node::Node -//***************************************************************************** -template -inline VpTree::Node::Node() - : theTree(0) -{ -} - -//***************************************************************************** -// VpTree::Node::Node -//***************************************************************************** -template -inline VpTree::Node::Node(VpTree* tree) - : theTree(tree) -{ -} - -//***************************************************************************** -// VpTree::Node::~Node -//***************************************************************************** -template -inline VpTree::Node::~Node() -{ - theTree = 0; -} - -//***************************************************************************** -// VpTree::Internal::Internal -//***************************************************************************** -template -inline VpTree::Internal::Internal() - : Node() - , theIndex(0) - , theInnerLowerBound(0) - , theInnerUpperBound(0) - , theOuterLowerBound(0) - , theOuterUpperBound(0) - , theInnerBranch(0) - , theOuterBranch(0) -{ -} - -//***************************************************************************** -// VpTree::Internal::Internal -//***************************************************************************** -template -inline VpTree::Internal::Internal(VpTree* tree) - : Node(tree) - , theIndex(0) - , theInnerLowerBound(0) - , theInnerUpperBound(0) - , theOuterLowerBound(0) - , theOuterUpperBound(0) - , theInnerBranch(0) - , theOuterBranch(0) -{ -} - -//***************************************************************************** -// VpTree::Internal::~Internal -//***************************************************************************** -template -inline VpTree::Internal::~Internal() -{ - delete theInnerBranch; - delete theOuterBranch; - theInnerBranch = 0; - theOuterBranch = 0; -} - -//***************************************************************************** -// VpTree::Leaf::Leaf -//***************************************************************************** -template -inline VpTree::Leaf::Leaf() - : Node() - , theHead(0) - , theTail(0) -{ -} - -//***************************************************************************** -// VpTree::Leaf::Leaf -//***************************************************************************** -template -inline VpTree::Leaf::Leaf(VpTree* tree, - const IndexT& head, - const IndexT& tail) - : Node(tree) - , theHead(head) - , theTail(tail) -{ -} - -//***************************************************************************** -// VpTree::Item::Item -//***************************************************************************** -template -inline VpTree::Item::Item() - : theIndex(0) - , theElement(0) - , theDistance(0) -{ -} - -//***************************************************************************** -// VpTree::Item::operator< -//***************************************************************************** -template -inline bool VpTree::Item::operator<(const Item& other) const -{ - return theDistance < other.theDistance; -} - -//***************************************************************************** -// VpTree::ResultsCandidate::ResultsCandidate -//***************************************************************************** -template -inline VpTree::ResultsCandidate::ResultsCandidate( - const IndexT& index, - const DistT& distance) - : theIndex(index) - , theDistance(distance) -{ -} - -//***************************************************************************** -// VpTree::ResultsCandidate::operator< -//***************************************************************************** -template -inline bool VpTree::ResultsCandidate::operator<( - const ResultsCandidate& other) const -{ - return theDistance < other.theDistance; -} - -//***************************************************************************** -// VpTree::randomSample + { + node->theInnerBranch = makeTree(innerLowerBound, outerLowerBound); + node->theOuterBranch = makeTree(outerLowerBound, stop); + } + + return node; +} + +//***************************************************************************** +// VpTree::randomSample(const IndexT&, const IndexT&) +//> Select a random sample in the range between the provided indices. +// +// @tparam MetricT The metric search space. +// @param start The beginning of the element range to transform into a +// binary tree. +// @param stop The end of the element range to transform into a binary +// tree. +// @return A set of randomly sampled elements from the provided +// range. +//< //***************************************************************************** template std::set::IndexT> VpTree::randomSample(const IndexT& start, - const IndexT& stop) const + const IndexT& stop) +const { //*** @@ -514,10 +309,22 @@ //***************************************************************************** -// VpTree::selectVp +// VpTree::selectVp(const IndexT&, const IndexT&) +//> Select a vantage point in the range between the provided indices. +// +// @tparam MetricT The metric search space. +// @param start The beginning of the element range to transform into a +// binary tree. +// @param stop The end of the element range to transform into a binary +// tree. +// @return Select a vantage point from the range of elements. +// +// @todo Implement a median of 5's to impose stability into the selection. +//< //***************************************************************************** template typename VpTree::IndexT VpTree::selectVp(const IndexT& start, - const IndexT& stop) const + const IndexT& stop) +const { //*** @@ -534,5 +341,5 @@ //*** -#if 0 +#if USE_OBSOLETED_CODE // Choose a point from a small sample set that maximizes spread std::set p=randomSample(start, stop); @@ -606,352 +413,3 @@ } -//***************************************************************************** -// VpTree::makeTree -//***************************************************************************** -template -typename VpTree::Node* -VpTree::makeTree(const IndexT& start, const IndexT& stop) -{ - if (stop <= start) return 0; - - IndexT setSize = stop - start; - - if (setSize <= theLeafCapacity) - { - return new Leaf(this, start, stop); - } - - Internal* node=new Internal(this); - node->theIndex=start; - - const IndexT vp = selectVp(start, stop); - std::swap(theItems[start], theItems[vp]); - - // Identify bound elements - IndexT outerLowerBound = (start + stop + 1)/2; - IndexT innerLowerBound = start + 1; - - // Update histories - DistT d_max=0; - DistT d_min=std::numeric_limits::max(); - for (IndexT elem = stop; elem --> innerLowerBound; ) - { - theItems[elem].theDistance = theMetric(theItems[start].theElement, - theItems[elem].theElement); - d_max = (theItems[elem].theDistance > d_max) - ? theItems[elem].theDistance : d_max; - d_min = (theItems[elem].theDistance < d_min) - ? theItems[elem].theDistance : d_min; - } - - // Put the median element in place - std::nth_element( - theItems.begin() + innerLowerBound, - theItems.begin() + outerLowerBound, - theItems.begin() + stop); - - DistT d_mid=0; - for (IndexT elem = outerLowerBound; elem --> innerLowerBound; ) - { - d_mid = (theItems[elem].theDistance > d_mid) - ? theItems[elem].theDistance : d_mid; - } - - node->theInnerLowerBound=d_min; - node->theInnerUpperBound=d_mid; - node->theOuterLowerBound=theItems[outerLowerBound].theDistance; - node->theOuterUpperBound=d_max; - - #if _OPENMP - static int threads = 0; - - if (threads < (omp_get_num_procs()-1)) - { - omp_set_dynamic(1); - omp_set_num_threads(omp_get_num_procs()); - omp_set_nested(1); - - #pragma omp atomic - ++threads; - - #pragma omp parallel - { - #pragma omp sections nowait - { - node->theInnerBranch = makeTree(innerLowerBound, - outerLowerBound); - - #pragma omp section - node->theOuterBranch = makeTree(outerLowerBound, stop); - } - } - - #pragma omp atomic - --threads; - } - else - #endif - { - node->theInnerBranch = makeTree(innerLowerBound, outerLowerBound); - node->theOuterBranch = makeTree(outerLowerBound, stop); - } - - return node; -} - -//***************************************************************************** -// VpTree::knn -//***************************************************************************** -template -typename VpTree::SearchResultsT -VpTree::knn(const PointT& query, - const IndexT& k, - const DistT& limit) const -{ - ResultsSetT candidates; - DistT tau = limit; - - theRoot->knn(query, k, candidates, tau); - - std::deque indices; - std::deque distances; - - - while(!candidates.empty()) - { - indices.push_back(theItems[candidates.top().theIndex].theIndex); - distances.push_back(candidates.top().theDistance); - candidates.pop(); - } - - std::reverse(indices.begin(), indices.end()); - std::reverse(distances.begin(), distances.end()); - - return std::make_pair(indices, distances); -} - -//***************************************************************************** -// VpTree::Internal::knn -//***************************************************************************** -template -void -VpTree::Internal::knn(const PointT& query, - const IndexT& k, - ResultsSetT& candidates, - DistT& kth_closest) const -{ - if (!(theTree)) return; - - DistT distance = theTree->theMetric(theTree->theItems[theIndex].theElement, - query); - - if (distance < kth_closest) - { - if (candidates.size() == k) - { - candidates.pop(); - } - - candidates.push(ResultsCandidate(theIndex, distance)); - - if (candidates.size() == k) - { - kth_closest = candidates.top().theDistance; - } - } - - if (!(theInnerBranch || theOuterBranch)) - { - return; - } - - DistT middle = static_cast - (0.5 * (theInnerUpperBound + theOuterLowerBound)); - - if (distance < middle) - { - if (theInnerBranch && - (distance - theInnerUpperBound <= kth_closest) && - (theInnerLowerBound - distance <= kth_closest)) - - - if (theInnerBranch && - (distance <= theInnerUpperBound + kth_closest) && - (distance >= theInnerLowerBound - kth_closest)) - { - theInnerBranch->knn(query, k, candidates, kth_closest); - } - - if (theOuterBranch && - (distance >= theOuterLowerBound - kth_closest) && - (distance <= theOuterUpperBound + kth_closest)) - { - theOuterBranch->knn(query, k, candidates, kth_closest); - } - } - else - { - if (theOuterBranch && - (distance >= theOuterLowerBound - kth_closest) && - (distance <= theOuterUpperBound + kth_closest)) - { - theOuterBranch->knn(query, k, candidates, kth_closest); - } - - if (theInnerBranch && - (distance <= theInnerUpperBound + kth_closest) && - (distance >= theInnerLowerBound - kth_closest)) - { - theInnerBranch->knn(query, k, candidates, kth_closest); - } - } -} - -//***************************************************************************** -// VpTree::Leaf::knn -//***************************************************************************** -template -void -VpTree::Leaf::knn(const PointT& query, - const IndexT& k, - ResultsSetT& candidates, - DistT& kth_closest) const -{ - if (!(theTree)) return; - - // Scan the leaf - for (IndexT item = theHead; item < theTail; ++item) - { - // This is the check state - DistT distance = theTree->theMetric(theTree->theItems[item].theElement, - query); - - if (distance < kth_closest) - { - if (candidates.size() == k) - { - candidates.pop(); - } - - candidates.push(ResultsCandidate(item, distance)); - - if (candidates.size() == k) - { - kth_closest = candidates.top().theDistance; - } - } - } -} - -//***************************************************************************** -// VpTree::rnn -//***************************************************************************** -template -typename VpTree::SearchResultsT -VpTree::rnn(const PointT& query, - const DistT& range) const -{ - ResultsSetT candidates; - - theRoot->rnn(query, range, candidates); - - std::deque indices; - std::deque distances; - - while(!candidates.empty()) - { - indices.push_back(theItems[candidates.top().theIndex].theIndex); - distances.push_back(candidates.top().theDistance); - candidates.pop(); - } - - std::reverse(indices.begin(), indices.end()); - std::reverse(distances.begin(), distances.end()); - - return std::make_pair(indices, distances); -} - -//***************************************************************************** -// VpTree::Internal::rnn -//***************************************************************************** -template -void VpTree::Internal::rnn(const PointT& query, - const DistT& range, - ResultsSetT& candidates) const -{ - if (!(theTree)) return; - - DistT distance = theTree->theMetric(theTree->theItems[theIndex].theElement, - query); - - if (distance <= range) - { - candidates.push(ResultsCandidate(theIndex, distance)); - } - - if (!(theInnerBranch || theOuterBranch)) - { - return; - } - - DistT middle = static_cast - (0.5 * (theInnerUpperBound + theOuterLowerBound)); - - if (distance < middle) - { - if (theInnerBranch && - (distance <= theInnerUpperBound + range) && - (distance >= theInnerLowerBound - range)) - { - theInnerBranch->rnn(query, range, candidates); - } - - if (theOuterBranch && - (distance >= theOuterLowerBound - range) && - (distance <= theOuterUpperBound + range)) - { - theOuterBranch->rnn(query, range, candidates); - } - } - else - { - if (theOuterBranch && - (distance >= theOuterLowerBound - range) && - (distance <= theOuterUpperBound + range)) - { - theOuterBranch->rnn(query, range, candidates); - } - - if (theInnerBranch && - (distance <= theInnerUpperBound + range) && - (distance >= theInnerLowerBound - range)) - { - theInnerBranch->rnn(query, range, candidates); - } - } -} - -//***************************************************************************** -// VpTree::Leaf::rnn -//***************************************************************************** -template -void VpTree::Leaf::rnn(const PointT& query, - const DistT& range, - ResultsSetT& candidates) const -{ - if (!(theTree)) return; - - // Scan the leaf - for (IndexT item = theHead; item < theTail; ++item) - { - DistT distance = theTree->theMetric(theTree->theItems[item].theElement, - query); - - if (distance <= range) - { - candidates.push(ResultsCandidate(item, distance)); - } - } -} - -} +} Index: mkjer/Util/SpatialIndexing/VpTree/VpTree.m =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree.m (revision 9) +++ (revision ) @@ -1,145 +1,0 @@ -% VpTree Vantage Point Tree spatial indexing data structure -% -% File: -% VpTree.m -% -% Description: -% This MATLAB class represents a vantage-point tree data structure. The -% class is derived from the MATLAB handle class to provide automated object -% descruction on calls to "clear". -% -% Limitations: -% See VpTree.h for complete description of limitations. -% -% Properties: -% None. -% -% Methods: -% [tree] = VpTree(varargin) - VP Tree Constructor -% delete(tree) - Release this object and -% free memory. -% [idx,dist] = knn(this, queries, k, varargin) - Perform a k-nearest -% neighbor search against -% the tree. -% [idx,dist] = rnn(this, data, radius) - Perform a fixed-radius -% nearest neighbor search -% against the tree. -% -% Toolbox requirements: -% None. -% -% Script requirements: -% None. -% -% Data requirements: -% VpTreeAPI MEX library. -% -% References: -% Yianilos, P. N. (1993). Data Structures and Algorithms for Nearest -% Neighbor Search in General Metric Spaces. In Proceedings of the Fourth -% Annual ACM-SIAM Symposium on Discrete Algorithms (pp. 311–321). SODA -% ’93. Philadelphia, PA, USA: Society for Industrial and Applied -% Mathematics. http://dl.acm.org/citation.cfm?id=313559.313789 -% -% See Also: -% None. -% - -% Copyright (C) 2012 Kristian L. Damkjer. -% -% Software History: -% 2012-AUG-29 K. Damkjer -% Initial Coding. -% - -classdef (Sealed = true) VpTree < handle - - properties (Hidden=true, Access = private) - % The C++ VP-tree object owned by this handle class. - theTree - end - - methods - function this = VpTree(varargin) - % This function builds the index structure for the database. - - if (nargin ~= 1) - error('VpTree:InvalidArgumentList',... - 'VpTree must be constructed with a set of observations'); - end - - this.theTree = VpTreeAPI('create', varargin{1}); - end - - function delete(this) - % This function frees memory on delete (clear) of the VpTree. - VpTreeAPI('destroy', this.theTree); - end - - function [idx,dist] = knn(this, queries, k, varargin) - % Perform a k-nearest neighbor search on the database with the - % set of queries. - - userParams = struct('limit', realmax); - - % Parse the Property/Value pairs - if rem(length(varargin), 2) ~= 0 - error('Damkjer:PropertyValueNotPair', ... - ['Additional arguments must take the form of'... - 'Property/Value pairs']); - end - - propertyNames = {'limit'}; - - while ~isempty(varargin) - property = varargin{1}; - value = varargin{2}; - - % If the property has been supplied in a shortened form, - % lengthen it - iProperty = find(strncmpi(property, propertyNames, ... - length(property))); - - if isempty(iProperty) - error('Damkjer:InvalidProperty', 'Invalid Property'); - elseif length(iProperty) > 1 - error('Damkjer:AmbiguousProperty', ... - 'Supplied shortened property name is ambiguous'); - end - - property = propertyNames{iProperty}; - - switch property - case 'limit' - if (isscalar(value) && isnumeric(value) && ... - isreal(value) && value > 0) - userParams.limit = value; - else - error('Damkjer:InvalidLimit', ... - 'Limit must be a real valued positive scalar'); - end - end - - varargin(1:2) = []; - end - - if (nargout == 1) - idx = VpTreeAPI('search_kann', this.theTree, queries, k, userParams.limit); - else - [idx,dist] = VpTreeAPI('search_kann', this.theTree, queries, k, userParams.limit); - end - end - - function [idx,dist] = rnn(this, queries, radius) - % Perform a fixed-radius nearest neighbor search on the - % database with the set of queries. - - if (nargout == 1) - idx = VpTreeAPI('search_frann', this.theTree, queries, radius); - else - [idx,dist] = VpTreeAPI('search_frann', this.theTree, queries, radius); - end - end - end -end - Index: mkjer/Util/SpatialIndexing/VpTree/VpTreeAPI.cpp =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTreeAPI.cpp (revision 10) +++ (revision ) @@ -1,761 +1,0 @@ -//***************************************************************************** -// FILE: VpTreeAPI.cpp -// -// Copyright (C) 2012 Kristian Damkjer. -// -// DESCRIPTION: This MATLAB Executable (MEX) gateway provides the application -// interface for working with VP Trees in MATLAB. All functional -// interfaces are routed through this single function to ensure -// locks and memory management are handled properly by MATLAB. -// -// LIMITATIONS: All interfaces to the VP Tree objects must be routed through -// this gateway file. This interface is required until and unless -// MATLAB provides a mechanism for modifying locks on MEX files -// other than the current file. -// -// SOFTWARE HISTORY: -//> 2012-SEP-11 K. Damkjer -// Initial Coding. -// 2013-JUL-19 K. Damkjer -// Improved structure and documentation. Prevented double free of -// VP Tree memory and infinite locking of MEX library. -// 2013-JUL-23 K. Damkjer -// Set typedefs to make code more readable and to allow for -// varying container and metric types. This is useful when the -// default double-precision is overkill. It is now easy to set -// types to float. -//< -//***************************************************************************** - -#if _OPENMP -#include -#endif - -#include "damkjerConfig.h" -#include "Util/MATLAB/ClassHandle.h" -#include "VpTree.h" - -// Fix "wide char" definition for older versions of MATLAB. This must be placed -// after other includes and before the mex.h include. -#if (defined(MATLAB_MAJOR) && defined(MATLAB_MINOR)) - #if MATLAB_MAJOR <= 7 && MATLAB_MINOR <= 10 && defined(_CHAR16T) - #define CHAR16_T - #endif -#endif - -#include "mex.h" - -namespace Damkjer -{ -typedef double VPTAPI_CoordT; -typedef std::vector VPTAPI_PointT; -typedef std::deque VPTAPI_PointSetT; -typedef EuclideanDistance VPTAPI_MetricT; -typedef VpTree VPTAPI_TreeT; - -//***************************************************************************** -// FUNCTION: vpTreeCreate -//***************************************************************************** -void vpTreeCreate(int, mxArray**, int, const mxArray**); -//> This function provides the interface to the VpTree contructors. New objects -// are wrapped by the ClassHandle template to ensure that locks are managed -// correctly to avoid double frees of memory managed by this class, to ensure -// objects have a life span separate from this function's scope, and to -// provide convenience methods for passing the pointer to the object between -// MATLAB and C++. -// -// See the VpTree class documentation for details on the method. -// -// The function signature is identical to the mexFunction gateway for -// convenience only. -//< - -//***************************************************************************** -// FUNCTION: vpTreeDestroy -//***************************************************************************** -void vpTreeDestroy(int, const mxArray**); -//> This function provides the interface to the VpTree ClassHandle wrapper -// destructor. Destroying objects through the ClassHandle wrapper ensures -// memory leaks are not introduced through this MEX function and allows the -// compiled MEX library to be unlocked once all objects have been destroyed -// and their memory returned to the system. -// -// See the VpTree class documentation for details on the method. -// -// The function signature is identical to the mexFunction gateway for -// convenience only. -//< - -//***************************************************************************** -// FUNCTION: vpTreeFRANN -//***************************************************************************** -void vpTreeFRANN(int nlhs, mxArray**, int nrhs, const mxArray**); -//> This function provides the interface to the VpTree fixed-radius all nearest -// neighbor (FRANN) search. -// -// See the VpTree class documentation for details on the method. -// -// The function signature is identical to the mexFunction gateway for -// convenience only. -//< - -//***************************************************************************** -// FUNCTION: vpTreeKANN -//***************************************************************************** -void vpTreeKANN(int nlhs, mxArray**, int nrhs, const mxArray**); -//> This function provides the interface to the VpTree k all nearest neighbor -// (KANN) search. -// -// See the VpTree class documentation for details on the method. -// -// The function signature is identical to the mexFunction gateway for -// convenience only. -//< -} - -//***************************************************************************** -// FUNCTION: mexFunction -// -//> The MATLAB Executable Gateway Function. -//< -//***************************************************************************** -void mexFunction(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) -{ - //*** - // This MEX function should always have at least one input parameter to - // handle function dispatching through the MEX gateway. - //*** - if (nrhs < 1) - { - mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:nargin", - "VpTreeAPI requires at least one input which " - "specifies the operation to be performed."); - } - - // The operation switch is simply a string. - char* operation = mxArrayToString(prhs[0]); - - if (!operation) - { - mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:InvalidOperation", - "Invalid mode supplied to VpTreeAPI."); - } - - // Dispatch to helper functions. Err if operation is not recognized. - if (!strcmp("create", operation)) - { - Damkjer::vpTreeCreate(nlhs, plhs, nrhs, prhs); - } - else if (!strcmp("destroy", operation)) - { - if (nlhs != 0) - { - mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:nargout", - "Nothing to return."); - } - - Damkjer::vpTreeDestroy(nrhs, prhs); - } - else if (!strcmp("search_frann", operation)) - { - Damkjer::vpTreeFRANN(nlhs, plhs, nrhs, prhs); - } - else if (!strcmp("search_kann", operation)) - { - Damkjer::vpTreeKANN(nlhs, plhs, nrhs, prhs); - } - else - { - mexErrMsgIdAndTxt("Damkjer:VpTreeAPI:UnknownOperation", - "Unrecognized mode provided to VpTreeAPI."); - } - - // Prevent a slow memory leak. - mxFree(operation); -} - -namespace Damkjer -{ -//***************************************************************************** -// FUNCTION: vpTreeCreate -//***************************************************************************** -void vpTreeCreate(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]) -{ - //*** - // Check parameters. Remember that we always have one "extra" input - // parameter to handle function dispatching through the MEX gateway. It - // always occupies the first input parameter position. - //*** - if (nrhs < 2 || nrhs > 2) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:nargin", - "The vpTreeCreate function requires a single input."); - } - - if (nlhs > 1) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:nargout", - "The vpTreeCreate function requires a single output."); - } - - //*** - // The single input required by vpTreeCreate is the collection of points to - // be indexed. - //*** - const mxArray* points=prhs[1]; - - // Check to make sure that points are real-valued numerics - if (mxIsSparse(points) || - mxGetNumberOfDimensions(points) != 2 || - mxIsComplex(points) || - !mxIsNumeric(points)) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:prhs", - "Input to vpTreeCreate must be a full, 2-D matrix " - "of real-valued data representing N-dimensional " - "observations."); - } - - // Attempt to make the VP Tree. - const mwSize dims = mxGetM(points); - const mwSize elems = mxGetN(points); - - double* data = mxGetPr(points); - - //*** - // Selection of data structure for the point database is not arbitrary. - // - // 1. Point coordinates are passed in as double-precision values. Preserve - // the data fidelity. - // 2. Individual points are often low-dimensional. Keep the coordinates for - // a single point in contiguous memory by using a std::vector container. - // 3. The point database can be quite large. Since VP Tree is an online data - // structure, allow references to points to occupy non-contiguous memory. - // This also speeds construction and destruction of the point database. - //*** - VPTAPI_PointSetT pointData(elems, VPTAPI_PointT(dims)); - - for (mwSize elem = elems; elem --> 0;) - { - for (mwSize dim = dims; dim --> 0;) - { - pointData[elem][dim]=(VPTAPI_CoordT)(data[elem*dims+dim]); - } - } - - //*** - // Use the ClassHandle named constructor to provide a handle to the new VP - // Tree object. - //*** - try - { - plhs[0] = ptrAsMat(new VPTAPI_TreeT(pointData, VPTAPI_MetricT())); - } - catch (const std::exception& e) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeCreate:initError", e.what()); - } -} - -//***************************************************************************** -// FUNCTION: vpTreeDestroy -//***************************************************************************** -void vpTreeDestroy(int nrhs, const mxArray** prhs) -{ - //*** - // Check parameters. Remember that we always have one "extra" input - // parameter to handle function dispatching through the MEX gateway. It - // always occupies the first input parameter position. - //*** - if (nrhs != 2 || !mxIsNumeric(prhs[1])) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeDestroy:varargin", - "The vpTreeDestroy function requires a single " - "input."); - } - - // Free the VP Tree through the ClassHandle named destructor. - destroyHandleTo(prhs[1]); -} - -//***************************************************************************** -// FUNCTION: vpTreeFRANN -//***************************************************************************** -void vpTreeFRANN(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) -{ - //*** - // Check parameters. Remember that we always have one "extra" input - // parameter to handle function dispatching through the MEX gateway. It - // always occupies the first input parameter position. - //*** - if (nrhs < 3 || nrhs > 4 || !mxIsNumeric(prhs[1])) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:varargin", - "Invalid number of input arguments."); - } - - if (nlhs>2) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:varargout", - "Invalid number of output arguments."); - } - - // Retrieve the tree object through the ClassHandle helper method. - const VPTAPI_TreeT& tree = matAsObj(prhs[1]); - - // The second parameter should be the query points. - const mxArray* queries=prhs[2]; - - // Check to make sure that query points are real-valued numerics - if (mxIsSparse(queries) || - mxGetNumberOfDimensions(queries) != 2 || - mxIsComplex(queries) || - !mxIsNumeric(queries)) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:prhs", - "Second input parameter to vpTreeFRANN must be a " - "full, 2-D matrix of real-valued data representing " - "multi-dimensional queries."); - } - - // The third parameter should be the query radius. - const mxArray* rData=prhs[3]; - - // Check to make sure that radius is a real-valued numeric scalar. - if (mxIsSparse(rData) || - mxGetNumberOfElements(rData) != 1 || - mxIsComplex(rData) || - !mxIsNumeric(rData)) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeFRANN:prhs", - "Third input parameter to vpTreeFRANN must be a " - "real-valued scalar representing desired neighborhood " - "radius limit."); - } - - //*** - // Get the query points. - // - // Selection of data structure for the query database is not arbitrary. - // - // 1. Point coordinates are passed in as double-precision values. Preserve - // the data fidelity. - // 2. Individual points are often low-dimensional. Keep the coordinates for - // a single point in contiguous memory by using a std::vector container. - // 3. The query database can be quite large. Allow references to points to - // occupy non-contiguous memory. - //*** - const mwSize dims = mxGetM(queries); - const mwSize elems = mxGetN(queries); - - double* data = mxGetPr(queries); - VPTAPI_PointSetT queryData(elems, VPTAPI_PointT(dims)); - - for (mwIndex elem = elems; elem --> 0;) - { - for (mwIndex dim = dims; dim --> 0;) - { - queryData[elem][dim]=(VPTAPI_CoordT)(data[elem*dims+dim]); - } - } - - // Get the desired neighborhood radius limit. - VPTAPI_TreeT::DistT radius = (VPTAPI_TreeT::DistT) - (*(double*)mxGetData(rData)); - - //*** - // The first output parameter holds the nearest neighbor indices. This - // collection is represented as a cell array of vectors with a cell for each - // query point. - //*** - plhs[0] = mxCreateCellMatrix(elems, 1); - - //*** - // If desired, the distance from the query point to each of the nearest - // neighbors can also be provided. This collection is represented as a cell - // array of vectors with a cell for each query point. - //*** - if (nlhs==2) - { - plhs[1] = mxCreateCellMatrix(elems, 1); - } - - //*** - // The following logic flows may seem counter-intuitive, but are structured - // to intentionally avoid nested critical sections in parallelized code. - // - // Unfortunately, any calls to the MATLAB API must be treated as belonging - // to a critical section since none of the API is thread-safe. - //*** - -#if _OPENMP - omp_set_dynamic(1); - omp_set_num_threads(omp_get_num_procs()); -#endif - - //*** - // The VP Tree data structure always provides results as a set of pairs of - // indices and distances. There is no performance benefit to omitting the - // distance computations since they are required for the search algorithm. - //*** - std::deque results(queryData.size()); - - //*** - // The first embarassingly parallelizable section simply searches for each - // query point's neighbors in parallel. This is much simpler than attempting - // to parallelize the search for a single point, and likely to yield - // superior results. - //*** - #pragma omp parallel for - for (int q = 0; q < queryData.size(); ++q) - { - results[q] = tree.rnn(queryData[q], radius); - } - - //*** - // Allocating memory for the results to be passed back to MATLAB must take - // place in a "critical section" since it involves exercising the MEX API. - //*** - std::deque nbr_idxs; - std::deque point_idxs; - - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - nbr_idxs.push_back(mxCreateNumericMatrix(0, 0, mxINDEX_CLASS, mxREAL)); - mxSetM(nbr_idxs[q], neighbors); - mxSetN(nbr_idxs[q], 1); - mxSetData(nbr_idxs[q], mxMalloc(sizeof(mwIndex)*neighbors*1)); - - point_idxs.push_back((mwIndex*)mxGetData(nbr_idxs[q])); - } - - //*** - // Once memory has been allocated, the actual results can be populated in - // parallel. - //*** - #pragma omp parallel for - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - mwIndex* idxs = point_idxs[q]; - - for (mwIndex idx = neighbors; idx --> 0;) - { - idxs[idx]=results[q].first[idx]+1; - } - } - - //*** - // Marking the data for return to MATLAB must take place in a "critical - // section" since it involves exercising the MEX API. This also changes - // ownership and memory management responsibilities to MATLAB. We will not - // free this data. - //*** - for (int q = 0; q < queryData.size(); ++q) - { - mxSetCell(plhs[0], q, nbr_idxs[q]); - } - - // Repeat the "hand-off" to MATLAB for distance data, if it was requested. - if (nlhs==2) - { - //*** - // Allocating memory for the results to be passed back to MATLAB must - // take place in a "critical section" since it involves exercising the - // MEX API. - //*** - std::deque nbr_dists; - std::deque point_dists; - - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - nbr_dists[q] = mxCreateDoubleMatrix(0, 0, mxREAL); - mxSetM(nbr_dists[q], neighbors); - mxSetN(nbr_dists[q], 1); - mxSetData(nbr_dists[q], mxMalloc(sizeof(double)*neighbors*1)); - - point_dists.push_back(mxGetPr(nbr_dists[q])); - } - - //*** - // Once memory has been allocated, the actual results can be populated in - // parallel. - //*** - #pragma omp parallel for - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - double* dists = point_dists[q]; - - for (mwIndex idx = neighbors; idx --> 0;) - { - dists[idx]=results[q].second[idx]; - } - } - - //*** - // Marking the data for return to MATLAB must take place in a "critical - // section" since it involves exercising the MEX API. This also changes - // ownership and memory management responsibilities to MATLAB. We will - // not free this data. - //*** - for (int q = 0; q < queryData.size(); ++q) - { - mxSetCell(plhs[1], q, nbr_dists[q]); - } - } -} - -//***************************************************************************** -// FUNCTION: vpTreeKANN -//***************************************************************************** -void vpTreeKANN(int nlhs, mxArray** plhs, int nrhs, const mxArray** prhs) -{ - //*** - // Check parameters. Remember that we always have one "extra" input - // parameter to handle function dispatching through the MEX gateway. It - // always occupies the first input parameter position. - //*** - if (nrhs != 5 || !mxIsNumeric(prhs[1])) - { - mexErrMsgIdAndTxt("Damkjer:kannVpTree:varargin", - "Invalid number of arguments"); - } - - // Retrieve the tree object through the ClassHandle helper method. - const VPTAPI_TreeT& tree = matAsObj(prhs[1]); - - // The second parameter should be the query points. - const mxArray* queries=prhs[2]; - - // Check to make sure that query points are real-valued numerics. - if (mxIsSparse(queries) || - mxGetNumberOfDimensions(queries) != 2 || - mxIsComplex(queries) || - !mxIsNumeric(queries)) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeKANN:prhs", - "Second input parameter to vpTreeKANN must be a full, " - "2-D matrix of real-valued data representing " - "multi-dimensional queries."); - } - - // The third parameter should be the desired neighborhood cardinality. - const mxArray* kData=prhs[3]; - - // Check to make sure that cardinality is a real-valued numeric scalar. - if (mxIsSparse(kData) || - mxGetNumberOfElements(kData) != 1 || - mxIsComplex(kData) || - !mxIsNumeric(kData)) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeKANN:prhs", - "Third input parameter to vpTreeKANN must be an " - "real-valued scalar representing desired neighborhood " - "cardinality."); - } - - // The fourth parameter should be the desired radius limit. - const mxArray* rData=prhs[4]; - - // Check to make sure that radius is a real-valued numeric scalar. - if (mxIsSparse(rData) || - mxGetNumberOfElements(rData) != 1 || - mxIsComplex(rData) || - !mxIsNumeric(rData)) - { - mexErrMsgIdAndTxt("Damkjer:vpTreeKANN:prhs", - "Fourth input parameter to vpTreeKANN must be an " - "real-valued scalar representing desired neighborhood " - "radius limit."); - } - - //*** - // Get the query points. - // - // Selection of data structure for the query database is not arbitrary. - // - // 1. Point coordinates are passed in as double-precision values. Preserve - // the data fidelity. - // 2. Individual points are often low-dimensional. Keep the coordinates for - // a single point in contiguous memory by using a std::vector container. - // 3. The query database can be quite large. Allow references to points to - // occupy non-contiguous memory. - //*** - const mwSize dims = mxGetM(queries); - const mwSize elems = mxGetN(queries); - - double* data = mxGetPr(queries); - VPTAPI_PointSetT queryData(elems, VPTAPI_PointT(dims)); - - for (mwIndex elem = elems; elem --> 0;) - { - for (mwIndex dim = dims; dim --> 0;) - { - queryData[elem][dim]=(VPTAPI_CoordT)(data[elem*dims+dim]); - } - } - - // Get the desired neighborhood cardinality. - mwSize k = (mwSize)(*((double*)mxGetData(kData))); - - // Get the desired neighborhood radius limit. - VPTAPI_TreeT::DistT radius = (VPTAPI_TreeT::DistT) - (*(double*)mxGetData(rData)); - - //*** - // The first output parameter holds the nearest neighbor indices. This - // collection is represented as a cell array of vectors with a cell for each - // query point. - //*** - plhs[0] = mxCreateCellMatrix(elems, 1); - - //*** - // If desired, the distance from the query point to each of the nearest - // neighbors can also be provided. This collection is represented as a cell - // array of vectors with a cell for each query point. - //*** - if (nlhs==2) - { - plhs[1] = mxCreateCellMatrix(elems, 1); - } - - //*** - // The following logic flows may seem counter-intuitive, but are structured - // to intentionally avoid nested critical sections in parallelized code. - // - // Unfortunately, any calls to the MATLAB API must be treated as belonging - // to a critical section since none of the API is thread-safe. - //*** - -#if _OPENMP - omp_set_dynamic(1); - omp_set_num_threads(omp_get_num_procs()); -#endif - - //*** - // The VP Tree data structure always provides results as a set of pairs of - // indices and distances. There is no performance benefit to omitting the - // distance computations since they are required for the search algorithm. - //*** - std::deque results(queryData.size()); - - //*** - // The first embarassingly parallelizable section simply searches for each - // query point's neighbors in parallel. This is much simpler than attempting - // to parallelize the search for a single point, and likely to yield - // superior results. - //*** - #pragma omp parallel for - for (int q = 0; q < queryData.size(); ++q) - { - results[q] = tree.knn(queryData[q], k, radius); - } - - //*** - // Allocating memory for the results to be passed back to MATLAB must take - // place in a "critical section" since it involves exercising the MEX API. - //*** - std::deque nbr_idxs; - std::deque point_idxs; - - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - nbr_idxs.push_back(mxCreateNumericMatrix(0, 0, mxINDEX_CLASS, mxREAL)); - mxSetM(nbr_idxs[q], neighbors); - mxSetN(nbr_idxs[q], 1); - mxSetData(nbr_idxs[q], mxMalloc(sizeof(mwIndex)*neighbors*1)); - - point_idxs.push_back((mwIndex*)mxGetData(nbr_idxs[q])); - } - - //*** - // Once memory has been allocated, the actual results can be populated in - // parallel. - //*** - #pragma omp parallel for - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - mwIndex* idxs = point_idxs[q]; - - for (mwIndex idx = neighbors; idx --> 0;) - { - idxs[idx]=results[q].first[idx]+1; - } - } - - //*** - // Marking the data for return to MATLAB must take place in a "critical - // section" since it involves exercising the MEX API. This also changes - // ownership and memory management responsibilities to MATLAB. We will not - // free this data. - //*** - for (int q = 0; q < queryData.size(); ++q) - { - mxSetCell(plhs[0], q, nbr_idxs[q]); - } - - // Repeat the "hand-off" to MATLAB for distance data, if it was requested. - if (nlhs==2) - { - //*** - // Allocating memory for the results to be passed back to MATLAB must - // take place in a "critical section" since it involves exercising the - // MEX API. - //*** - std::deque nbr_dists; - std::deque point_dists; - - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - nbr_dists[q] = mxCreateDoubleMatrix(0, 0, mxREAL); - mxSetM(nbr_dists[q], neighbors); - mxSetN(nbr_dists[q], 1); - mxSetData(nbr_dists[q], mxMalloc(sizeof(double)*neighbors*1)); - - point_dists.push_back(mxGetPr(nbr_dists[q])); - } - - //*** - // Once memory has been allocated, the actual results can be populated in - // parallel. - //*** - #pragma omp parallel for - for (int q = 0; q < queryData.size(); ++q) - { - mwSize neighbors = results[q].first.size(); - - double* dists = point_dists[q]; - - for (mwIndex idx = neighbors; idx --> 0;) - { - dists[idx]=results[q].second[idx]; - } - } - - //*** - // Marking the data for return to MATLAB must take place in a "critical - // section" since it involves exercising the MEX API. This also changes - // ownership and memory management responsibilities to MATLAB. We will - // not free this data. - //*** - for (int q = 0; q < queryData.size(); ++q) - { - mxSetCell(plhs[1], q, nbr_dists[q]); - } - } -} - -} Index: mkjer/Util/SpatialIndexing/VpTree/VpTreeAPI.vcxproj =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTreeAPI.vcxproj (revision 10) +++ (revision ) @@ -1,214 +1,0 @@ - - - - - Debug - Win32 - - - Debug - x64 - - - OpenMP - Win32 - - - OpenMP - x64 - - - Release - Win32 - - - Release - x64 - - - - - - - - {20fe2624-c64f-d61a-bd8f-1725a8e68a42} - - - - Win32Proj - VpTreeAPI - - - - DynamicLibrary - true - - - DynamicLibrary - true - - - DynamicLibrary - false - - - DynamicLibrary - false - - - DynamicLibrary - false - - - DynamicLibrary - false - - - - - - - - - - - - - - - - - - - - - - - - - .mexw32 - $(SolutionDir)lib\$(Platform)\$(Configuration)\ - $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ - - - .mexw64 - $(SolutionDir)lib\$(Platform)\$(Configuration)\ - $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ - - - .mexw32 - $(SolutionDir)lib\$(Platform)\$(Configuration)\ - $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ - - - .mexw32 - $(SolutionDir)lib\$(Platform)\$(Configuration)\ - $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ - - - .mexw64 - $(SolutionDir)lib\$(Platform)\$(Configuration)\ - $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ - - - .mexw64 - $(SolutionDir)lib\$(Platform)\$(Configuration)\ - $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ - - - - _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) - MultiThreadedDebugDLL - Level4 - Disabled - $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) - - - MachineX86 - true - libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) - $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) - - - - - _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) - MultiThreadedDebugDLL - Level4 - Disabled - $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) - - - true - libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) - $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) - - - - - _USE_MATH_DEFINES;WIN32;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) - MultiThreadedDLL - Level4 - $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) - - - MachineX86 - true - true - true - libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) - $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) - - - - - _USE_MATH_DEFINES;WIN32;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) - MultiThreadedDLL - Level4 - $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) - true - - - MachineX86 - true - true - true - libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) - $(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) - - - - - _USE_MATH_DEFINES;WIN64;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) - MultiThreadedDLL - Level4 - $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) - - - true - true - true - libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) - $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) - - - - - _USE_MATH_DEFINES;WIN64;NDEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) - MultiThreadedDLL - Level4 - $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) - true - - - true - true - true - libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) - $(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) - - - - - - Index: mkjer/Util/SpatialIndexing/VpTree/VpTreeAPI.vcxproj.filters =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTreeAPI.vcxproj.filters (revision 9) +++ (revision ) @@ -1,18 +1,0 @@ - - - - - {4010ed24-e68d-4e6e-97b0-8b8bb335aa86} - cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx - - - {0c039d31-de79-478b-9dc5-c3378145e52a} - h;hpp;hxx;hm;inl;inc;xsd - - - - - Source Files - - - Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_Branch.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_Branch.h (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_Branch.h (revision 12) @@ -0,0 +1,178 @@ +//***************************************************************************** +// FILE: VpTree_Branch.h +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The interface definition for vantage-point tree branches. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** +#ifndef Damkjer_VpTree_Branch_HEADER +#define Damkjer_VpTree_Branch_HEADER + +#if _OPENMP +#include +#endif + +#include +#include + +#include "VpTree_Node.h" // ISA Damkjer::VpTree::Node + +namespace Damkjer +{ + +//***************************************************************************** +// CLASS: VpTree::Branch +//> A vantage-point tree internal (non-terminal) node. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +class VpTree::Branch : public VpTree::Node +{ +public: + Branch(); + //> Instantiate a null node. + //< + + Branch(VpTree*); + //> Instantiate a node with a database reference. + //< + + virtual ~Branch(); + //> Destruct the node and deallocate resources. + //< + + virtual void knn(const PointT&, + const IndexT&, + ResultsSetT&, + DistT&) const; + //> Accumulate the k nearest neighbor results. + //< + + virtual void rnn(const PointT&, + const DistT&, + ResultsSetT&) const; + //> Accumulate the fixed-radius nearest neighbor results. + //< + +private: + + IndexT theIndex; + //> The index of the item in the internal database. + //< + + DistT theInnerLowerBound; + //> The lower bound distance to elements on inner branch. + //< + + DistT theInnerUpperBound; + //> The uuper bound distance to elements on inner branch. + //< + + DistT theOuterLowerBound; + //> The lower bound distance to elements on outer branch. + //< + + DistT theOuterUpperBound; + //> The upper bound distance to elements on outer branch. + //< + + Node* theInnerBranch; + //> The inner branch partition containing elements closer than + // the median partition to this element. + //< + + Node* theOuterBranch; + //> The outer branch partition containing elements at or beyond + // the median partition from this element. + //< + + friend class VpTree; + //> Provide access to branch internals to the containing tree class. + //< +}; + +//***************************************************************************** +// VpTree::Branch::Branch +//> Instantiate a null node. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::Branch::Branch() + : Node() + , theIndex(0) + , theInnerLowerBound(0) + , theInnerUpperBound(0) + , theOuterLowerBound(0) + , theOuterUpperBound(0) + , theInnerBranch(0) + , theOuterBranch(0) +{ +} + +//***************************************************************************** +// VpTree::Branch::Branch +//> Instantiate a node with a database reference. +// +// @tparam MetricT The metric search space. +// @param tree The vantage point tree containing the item database. +//< +//***************************************************************************** +template +inline +VpTree::Branch::Branch(VpTree* tree) + : Node(tree) + , theIndex(0) + , theInnerLowerBound(0) + , theInnerUpperBound(0) + , theOuterLowerBound(0) + , theOuterUpperBound(0) + , theInnerBranch(0) + , theOuterBranch(0) +{ +} + +//***************************************************************************** +// VpTree::Branch::~Branch +//> Destruct the node and deallocate resources. Virtual to ensure proper node +// destruction. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::Branch::~Branch() +{ + delete theInnerBranch; + delete theOuterBranch; + theInnerBranch = 0; + theOuterBranch = 0; +} + +} + +#include "VpTree_Branch.hpp" + +#endif Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_Branch.hpp =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_Branch.hpp (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_Branch.hpp (revision 12) @@ -0,0 +1,195 @@ +//***************************************************************************** +// FILE: VpTree_Branch.hpp +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The template implementation for vantage-point tree branches. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** + +#if _OPENMP +#include +#endif + +#include +#include + +#include "VpTree_Branch.h" + +namespace Damkjer +{ + +//***************************************************************************** +// VpTree::Branch::knn +//> Accumulate the k nearest neighbor results. +// +// @tparam MetricT The metric search space. +// @param[in] query The query point to focus the search about. +// @param[in] k The number of neighbors to identify. +// @param[in,out] candidates The set of candidate results. +// @param[in,out] kth_closest The distance to the kth-closest item. +//< +//***************************************************************************** +template +void +VpTree::Branch::knn(const PointT& query, + const IndexT& k, + ResultsSetT& candidates, + DistT& kth_closest) +const +{ + if (!(this->theTree)) return; + + DistT distance = this->theTree->theMetric( + this->theTree->theItems[theIndex].theElement, + query); + + if (distance < kth_closest) + { + if (candidates.size() == k) + { + candidates.pop(); + } + + candidates.push(ResultsCandidate(theIndex, distance)); + + if (candidates.size() == k) + { + kth_closest = candidates.top().theDistance; + } + } + + if (!(theInnerBranch || theOuterBranch)) + { + return; + } + + DistT middle = static_cast + (0.5 * (theInnerUpperBound + theOuterLowerBound)); + + if (distance < middle) + { + if (theInnerBranch && + (distance - theInnerUpperBound <= kth_closest) && + (theInnerLowerBound - distance <= kth_closest)) + + + if (theInnerBranch && + (distance <= theInnerUpperBound + kth_closest) && + (distance >= theInnerLowerBound - kth_closest)) + { + theInnerBranch->knn(query, k, candidates, kth_closest); + } + + if (theOuterBranch && + (distance >= theOuterLowerBound - kth_closest) && + (distance <= theOuterUpperBound + kth_closest)) + { + theOuterBranch->knn(query, k, candidates, kth_closest); + } + } + else + { + if (theOuterBranch && + (distance >= theOuterLowerBound - kth_closest) && + (distance <= theOuterUpperBound + kth_closest)) + { + theOuterBranch->knn(query, k, candidates, kth_closest); + } + + if (theInnerBranch && + (distance <= theInnerUpperBound + kth_closest) && + (distance >= theInnerLowerBound - kth_closest)) + { + theInnerBranch->knn(query, k, candidates, kth_closest); + } + } +} + +//***************************************************************************** +// VpTree::Branch::rnn +//> Accumulate the fixed-radius nearest neighbor results. +// +// @tparam MetricT The metric search space. +// @param[in] query The query point to focus the search about. +// @param[in] range The radial distance used to bound the search. +// @param[in,out] candidates The set of candidate results. +//< +//***************************************************************************** +template +void +VpTree::Branch::rnn(const PointT& query, + const DistT& range, + ResultsSetT& candidates) +const +{ + if (!(this->theTree)) return; + + DistT distance = this->theTree->theMetric( + this->theTree->theItems[theIndex].theElement, + query); + + if (distance <= range) + { + candidates.push(ResultsCandidate(theIndex, distance)); + } + + if (!(theInnerBranch || theOuterBranch)) + { + return; + } + + DistT middle = static_cast + (0.5 * (theInnerUpperBound + theOuterLowerBound)); + + if (distance < middle) + { + if (theInnerBranch && + (distance <= theInnerUpperBound + range) && + (distance >= theInnerLowerBound - range)) + { + theInnerBranch->rnn(query, range, candidates); + } + + if (theOuterBranch && + (distance >= theOuterLowerBound - range) && + (distance <= theOuterUpperBound + range)) + { + theOuterBranch->rnn(query, range, candidates); + } + } + else + { + if (theOuterBranch && + (distance >= theOuterLowerBound - range) && + (distance <= theOuterUpperBound + range)) + { + theOuterBranch->rnn(query, range, candidates); + } + + if (theInnerBranch && + (distance <= theInnerUpperBound + range) && + (distance >= theInnerLowerBound - range)) + { + theInnerBranch->rnn(query, range, candidates); + } + } +} + +} Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_Item.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_Item.h (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_Item.h (revision 12) @@ -0,0 +1,138 @@ +//***************************************************************************** +// FILE: VpTree_Item.h +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The interface definition for vantage-point tree items. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** +#ifndef Damkjer_VpTree_Item_HEADER +#define Damkjer_VpTree_Item_HEADER + +#if _OPENMP +#include +#endif + +#include +#include + +#include "VpTree.h" + +namespace Damkjer +{ + +//***************************************************************************** +// CLASS: VpTree::Item +//> A simple container to capture a database element along with its index and +// ancestral pivot history. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +class VpTree::Item +{ +public: + Item(); + //> The default constructor creates a blank item. + //< + + //*** + // Use the compiler-generated copy constructor. + // Item(const Item&); + //*** + + ~Item(){} + //> The default destructor. Intentionally non-virtual since Node is + // a private inner class on VpTree. + //< + + //*** + // Use the compiler-generated assignment operator. + // Item& operator=(const Item&); + //*** + + bool operator<(const Item&) const; + //> Less-than comparison for vantage point tree items. + //< + +private: + IndexT theIndex; + //> The index of the item in the input data set. + //< + + PointT theElement; + //> The database object + //< + + DistT theDistance; + //> The most recent ancestral pivot history distance for this item. + //< + + friend class VpTree; + //> Provide access to item internals to the containing tree class. + //< +}; + +//***************************************************************************** +// VpTree::Item::Item() +//> The default constructor creates a blank item. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::Item::Item() + : theIndex(0) + , theElement(0) + , theDistance(0) +{ +} + +//***************************************************************************** +// VpTree::Item::operator<(const Item&) +//> Less-than comparison for vantage point tree items. +// +// @note +// In general, the other members of the comparison operator family should be +// implemented. They are not in the case of vantage point tree items because +// the less-than comparitor is only used in sorting semantics. The remaining +// operators would thus be defined, but never used since items are private +// to the vantage point tree. +// +// @tparam MetricT The metric search space. +// @param other The vantage point tree item for comparison against this +// item. +// @return true if and only if this item is closer to the query than +// the other item. +//< +//***************************************************************************** +template +inline +bool +VpTree::Item::operator<(const Item& other) +const +{ + return theDistance < other.theDistance; +} + +} + +#endif Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_Leaf.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_Leaf.h (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_Leaf.h (revision 12) @@ -0,0 +1,131 @@ +//***************************************************************************** +// FILE: VpTree_Leaf.h +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The interface definition for vantage-point tree leaves. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** +#ifndef Damkjer_VpTree_LeafNode_HEADER +#define Damkjer_VpTree_LeafNode_HEADER + +#if _OPENMP +#include +#endif + +#include +#include + +#include "VpTree_Node.h" + +namespace Damkjer +{ + +//***************************************************************************** +// CLASS: VpTree::Leaf +//> A vantage-point tree terminal node. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +class VpTree::Leaf : public VpTree::Node +{ +public: + Leaf(); + //> Instantiate a null node. + //< + + Leaf(VpTree*, const IndexT&, const IndexT&); + //> Instantiate a leaf with a database reference that represents the + // items in the provided index range. + //< + + virtual ~Leaf(){} + //> Destruct the node and deallocate resources. + // + // @tparam MetricT The metric search space. + //< + + virtual void knn(const PointT&, + const IndexT&, + ResultsSetT&, + DistT&) const; + //> Accumulate the k nearest neighbor results. + //< + + virtual void rnn(const PointT&, + const DistT&, + ResultsSetT&) const; + //> Accumulate the fixed-radius nearest neighbor results. + //< + +private: + IndexT theHead; + //> The start of the index range represented by this leaf node. + //< + + IndexT theTail; + //> The end of the index range represented by this leaf node. + //< +}; + +//***************************************************************************** +// VpTree::Leaf::Leaf +//> Instantiate a null node. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::Leaf::Leaf() + : Node() + , theHead(0) + , theTail(0) +{ +} + +//***************************************************************************** +// VpTree::Leaf::Leaf +//> Instantiate a leaf with a database reference that represents the items in +// the provided index range. +// +// @tparam MetricT The metric search space. +// @param tree The vantage point tree containing the item database. +// @param head The start of the item index range. +// @param tail The end of the item index range. +//< +//***************************************************************************** +template +inline +VpTree::Leaf::Leaf(VpTree* tree, + const IndexT& head, + const IndexT& tail) + : Node(tree) + , theHead(head) + , theTail(tail) +{ +} + +} + +#include "VpTree_Leaf.hpp" + +#endif Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_Leaf.hpp =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_Leaf.hpp (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_Leaf.hpp (revision 12) @@ -0,0 +1,117 @@ +//***************************************************************************** +// FILE: VpTree_Leaf.hpp +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The template implementation for vantage-point tree leaves. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** + +#if _OPENMP +#include +#endif + +#include +#include + +#include "VpTree_Leaf.h" + +namespace Damkjer +{ + +//***************************************************************************** +// VpTree::Leaf::knn +//> Accumulate the k nearest neighbor results. +// +// @tparam MetricT The metric search space. +// @param[in] query The query point to focus the search about. +// @param[in] k The number of neighbors to identify. +// @param[in,out] candidates The set of candidate results. +// @param[in,out] kth_closest The distance to the kth-closest item. +//< +//***************************************************************************** +template +void +VpTree::Leaf::knn(const PointT& query, + const IndexT& k, + ResultsSetT& candidates, + DistT& kth_closest) +const +{ + if (!(this->theTree)) return; + + // Scan the leaf + for (IndexT item = theHead; item < theTail; ++item) + { + // This is the check state + DistT distance = this->theTree->theMetric( + this->theTree->theItems[item].theElement, + query); + + if (distance < kth_closest) + { + if (candidates.size() == k) + { + candidates.pop(); + } + + candidates.push(ResultsCandidate(item, distance)); + + if (candidates.size() == k) + { + kth_closest = candidates.top().theDistance; + } + } + } +} + +//***************************************************************************** +// VpTree::Leaf::rnn +//> Accumulate the fixed-radius nearest neighbor results. +// +// @tparam MetricT The metric search space. +// @param[in] query The query point to focus the search about. +// @param[in] range The radial distance used to bound the search. +// @param[in,out] candidates The set of candidate results. +//< +//***************************************************************************** +template +void +VpTree::Leaf::rnn(const PointT& query, + const DistT& range, + ResultsSetT& candidates) +const +{ + if (!(this->theTree)) return; + + // Scan the leaf + for (IndexT item = theHead; item < theTail; ++item) + { + DistT distance = this->theTree->theMetric( + this->theTree->theItems[item].theElement, + query); + + if (distance <= range) + { + candidates.push(ResultsCandidate(item, distance)); + } + } +} + +} Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_Node.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_Node.h (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_Node.h (revision 12) @@ -0,0 +1,126 @@ +//***************************************************************************** +// FILE: VpTree_Node.h +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The interface definition for vantage-point tree nodes. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** +#ifndef Damkjer_VpTree_Node_HEADER +#define Damkjer_VpTree_Node_HEADER + +#include "VpTree.h" // ISA Damkjer::VpTree inner class; + +namespace Damkjer +{ + +//***************************************************************************** +// CLASS: VpTree::Node +//> An abstract node interface for vantage point tree elements. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +class VpTree::Node +{ +public: + Node(); + //> Instantiate a null node. + //< + + Node(VpTree* const); + //> Instantiate a node with a database reference. + //< + + virtual ~Node(); + //> Destruct the node and deallocate resources. + //< + + virtual void knn(const PointT&, + const IndexT&, + ResultsSetT&, + DistT&) const = 0; + //> Accumulate the k nearest neighbor results. + //< + + virtual void rnn(const PointT&, + const DistT&, + ResultsSetT&) const = 0; + //> Accumulate the fixed-radius nearest neighbor results. + //< + +protected: + VpTree* theTree; + //> The tree that this node belongs to. + // + // Establishes an explicit relationship between the containing class and + // nested class. Included to avoid reallocating contained element data + // for each node. As a side effect, nodes organize the tree's data + // contents through the construction process. + //< +}; + +//***************************************************************************** +// VpTree::Node::Node +//> Instantiate a null node. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::Node::Node() + : theTree(0) +{ +} + +//***************************************************************************** +// VpTree::Node::Node +//> Instantiate a node with a database reference. +// +// @tparam MetricT The metric search space. +// @param tree The vantage point tree containing the item database. +//< +//***************************************************************************** +template +inline +VpTree::Node::Node(VpTree* tree) + : theTree(tree) +{ +} + +//***************************************************************************** +// VpTree::Node::~Node +//> Destruct the node and deallocate resources. Virtual to ensure proper node +// destruction. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +inline +VpTree::Node::~Node() +{ + theTree = 0; +} + +} + +#endif Index: Damkjer/Util/SpatialIndexing/VpTree/VpTree_ResultsCandidate.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/VpTree_ResultsCandidate.h (revision 12) +++ Damkjer/Util/SpatialIndexing/VpTree/VpTree_ResultsCandidate.h (revision 12) @@ -0,0 +1,143 @@ +//***************************************************************************** +// FILE: VpTree_ResultsCandidate.h +// +// Copyright (C) 2012 Kristian Damkjer. +// +// DESCRIPTION: +//> The interface definition for vantage-point tree search result candidates. +//< +// +// LIMITATIONS: +//> This class template file is a section of the Damkjer::VpTree interface +// definition and should not be directly included. +//< +// +// SOFTWARE HISTORY: +//> 2012-SEP-11 K. Damkjer +// Initial Coding. +// 2013-JUL-23 K. Damkjer +// Set typedefs to make code more readable and to allow for +// varying container and metric types. This is useful when the +// default double-precision is overkill. It is now easy to set +// types to float. +//< +//***************************************************************************** +#ifndef Damkjer_VpTree_ResultsCandidate_HEADER +#define Damkjer_VpTree_ResultsCandidate_HEADER + +#if _OPENMP +#include +#endif + +#include +#include + +#include "VpTree.h" + +namespace Damkjer +{ + +//***************************************************************************** +// VpTree::ResultsCandidate +//> A light-weight representation of a search result candidate item. +// +// @tparam MetricT The metric search space. +//< +//***************************************************************************** +template +class VpTree::ResultsCandidate +{ +public: + + //*** + // Use the compiler-generated default constructor. + // ResultsCandidate(); + //*** + + ResultsCandidate(const IndexT&, const DistT&); + //> Instantiate a light-weight results candidate. + //< + + //*** + // Use the compiler-generated copy constructor. + // ResultsCandidate(const ResultsCandidate&); + //*** + + ~ResultsCandidate(){} + //> The default destructor. Intentionally non-virtual since + // ResultsCandidate is a private inner class on VpTree. + // + // @tparam MetricT The metric search space. + //< + + //*** + // Use the compiler-generated assignment operator. + // ResultsCandidate& operator=(const ResultsCandidate&); + //*** + + bool operator<(const ResultsCandidate&) const; + //> Compare result candidate distances to determine which is closer + // to the query. + //< + +private: + IndexT theIndex; + //> The index of the candidate in the internal database. + //< + + DistT theDistance; + //> The candidate's distance to the query point. + //< + + friend class VpTree; + //> Provide access to results candidate internals to the containing tree + // class. + //< +}; + +//***************************************************************************** +// VpTree::ResultsCandidate::ResultsCandidate +//> Instantiate a light-weight results candidate. +// +// @tparam MetricT The metric search space. +// @param index The candidate database index. +// @param distance The candidate distance to the query. +//< +//***************************************************************************** +template +inline +VpTree::ResultsCandidate::ResultsCandidate(const IndexT& index, + const DistT& distance) + : theIndex(index) + , theDistance(distance) +{ +} + +//***************************************************************************** +// VpTree::ResultsCandidate::operator< +//> Less-than comparison for vantage point tree results candidates. +// +// @note +// In general, the other members of the comparison operator family should be +// implemented. They are not in the case of vantage point tree results +// candidates because the less-than comparitor is only used in sorting +// semantics. The remaining operators would thus be defined, but never used +// since items are private to the vantage point tree. +// +// @param other The result candidate for comparison against this item. +// @return true if and only if this candidate is closer to the query +// than the other candidate. +//< +//***************************************************************************** +template +inline +bool +VpTree::ResultsCandidate::operator<(const ResultsCandidate& other) +const +{ + return theDistance < other.theDistance; +} + +} + +#endif Index: mkjer/Util/SpatialIndexing/VpTree/makeVpTree.m =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/makeVpTree.m (revision 7) +++ (revision ) @@ -1,121 +1,0 @@ -% makeVpTree Build VpTree spatial indexing library MEX functions and classes. -% -% File: -% makeVpTree.m -% -% Description: -% This MATLAB function provides an simplified interface for building the -% VpTree C++ and MEX files. -% -% Limitations: -% Assumes mex -setup has been successfully run. -% -% Synopsis: -% makeVpTree(options...) -% -% Inputs: -% Option strings may be provided as abbreviations as long as they resolve to -% a unique option. -% -% 'debug' - Compile with debug flags and fully populated symbol table. -% 'parallel' - Enable OpenMP pragmas for multi-threaded computing. -% 'verbose' - Provide verbose output while compiling. -% 'warnings' - Provide compiler warning output for production-ready code. -% Implies 'verbose'. -% -% Outputs: -% None. -% -% Toolbox requirements: -% None. -% -% Script requirements: -% None. -% -% Data requirements: -% None. -% -% References: -% None. -% -% See Also: -% VpTree -% - -% Software History: -% 2012-AUG-29 K. Damkjer -% Initial Coding. -% 2013-JUN-17 K. Damkjer -% Additional Commenting. -% - -function makeVpTree(varargin) - -command = 'mex -largeArrayDims -DTEMPLATE_INCLUSION'; - -matlab_ver = regexp(version, '[. ]', 'split'); -command = [command... - ' -DMATLAB_MAJOR=' matlab_ver{1}... - ' -DMATLAB_MINOR=' matlab_ver{2}... - ' -DMATLAB_REVIS=' matlab_ver{3}... - ' -DMATLAB_BUILD=' matlab_ver{4}... - ' -DMATLAB_REL=' matlab_ver{5}(2:end-1)]; - -flags = {'verbose', 'debug', 'warnings', 'parallel'}; -options = ''; - -while ~isempty(varargin) - flag = varargin{1}; - - % If the property has been supplied in a shortened form, lengthen it - iFlag = find(strncmpi(flag, flags, length(flag))); - - if isempty(iFlag) - % Pass through any arguments we don't recognize - options = strcat(options, ' ', flag); - - % Alternatively, escalate to an error. - %error('Damkjer:makeVpTree:InvalidFlag', ['Invalid Flag: ' flag]); - elseif length(iFlag) > 1 - error('Damkjer:makeVpTree:AmbiguousFlag', ... - ['Supplied shortened flag is ambiguous: ' flag]); - else - flag = flags{iFlag}; - - switch flag - case 'verbose' - command = strcat(command, ' -v'); - case 'debug' - command = strcat(command, ' -g'); - case 'parallel' - if (ispc) - command = strcat(command, ' COMPFLAGS="$COMPFLAGS /openmp"'); - else - command = strcat(command, ' CFLAGS="\$CFLAGS -fopenmp"',... - ' CXXFLAGS="\$CXXFLAGS -fopenmp"',... - ' LDFLAGS="\$LDFLAGS -fopenmp"'); - end - case 'warnings' - if (ispc) - command = strcat(command, ' -v COMPFLAGS="$COMPFLAGS -W3"'); - else - command = strcat(command, ' -v',... - ' CFLAGS="\$CFLAGS -Wall -Wextra"',... - ' CXXFLAGS="\$CXXFLAGS -Wall -Wextra"'); - end - otherwise - error('Damkjer:makeVpTree:NotImplementedFlag', ... - ['Flag recognized, but not supported: ' flag]); - end - end - - varargin(1) = []; -end - -[path,~,~]=fileparts(mfilename('fullpath')); -command = [command options ' -I' fullfile(path,'..','..','..')... - ' -outdir ' path ' ' path '/']; - -eval([command 'VpTreeAPI.cpp']); - -end Index: Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.cpp =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.cpp (revision 10) +++ Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.cpp (revision 12) @@ -23,6 +23,6 @@ #include -#include "damkjerConfig.h" #include "TestVpTree.h" +#include "Util/Exception/Exception.h" #include "Util/SpatialIndexing/Metrics/Metrics.h" #include "Util/SpatialIndexing/VpTree/VpTree.h" @@ -33,12 +33,15 @@ //***************************************************************************** -// FUNCTOR: testEuclidean -//***************************************************************************** -template -class testKnn : public TestCase::TestStep +// FUNCTOR: testEuclideanKnn +//***************************************************************************** +template +class testEuclideanKnn : public TestCase::TestStep { public: - testKnn() - : TestCase::TestStep(typeid(VpTree).name()) + testEuclideanKnn() + : TestCase::TestStep((std::string( + "k nearest-neighbor algorithm in Euclidean space " + "for points of type: ") + + typeid(PointT).name())) { } @@ -48,9 +51,33 @@ bool operator()(TestCase& test) const { - EXCEPTION_TRY("Damkjer::testEuclidean::operator(TestCase&)"); - - typedef typename MetricT::value_type PointT; - - std::deque theData; + EXCEPTION_TRY("Damkjer::testEuclideanKnn::operator(TestCase&)"); + + typedef typename PointT::value_type ValueT; + typedef EuclideanDistance MetricT; + typedef typename MetricT::return_type DistT; + + //*** + // Set up a 2D point layout on a regular grid as follows: + // + //- (0,0) (0,1) (0,2) ... (0,9) + //- (1,0) (1,1) (1,2) ... (1,9) + //- . . . . . + //- . . . . . + //- . . . . . + //- (9,0) (9,1) (9,2) ... (9,9) + // + // Make sure points are created in top-left to bottom-right row-major + // order to force known indices: + // + //- 0 1 2 ... 9 + //- 10 11 12 ... 19 + //- . . . . . + //- . . . . . + //- . . . . . + //- 90 91 92 ... 99 + // + //*** + + std::deque data; for (unsigned int row = 0; row < 10; ++row) @@ -59,17 +86,48 @@ { PointT pt; - pt.push_back(static_cast(row)); - pt.push_back(static_cast(col)); - theData.push_back(pt); - } - } - + pt.push_back(static_cast(row)); + pt.push_back(static_cast(col)); + data.push_back(pt); + } + } + + // Create the spatially indexed database typedef VpTree VpTreeT; - VpTreeT theDatabase(theData); - VpTreeT::SearchResultsT results = theDatabase.knn(theData[45], 20); - - std::deque idxs = results.first; - std::deque dists = results.second; + VpTreeT database(data); + typedef typename VpTreeT::IndexT IndexT; + typedef typename VpTreeT::SearchResultsT SearchResultsT; + + // Perform a search for the 20 nearest neighbors to point 45. + SearchResultsT results = database.knn(data[45], 20); + + //*** + // In Euclidean space, the results should belong to the following set: + // + //- 24 25 26 + //- 33 34 35 36 37 + //- 43 44 45 46 47 + //- 53 54 55 56 57 + //- 64 65 66 + // + // With distances: + // + //- 2.23607 2.00000 2.23607 + //- 2.23607 1.41421 1.00000 1.41421 2.23607 + //- 2.00000 1.00000 0.00000 1.00000 2.00000 + //- 2.23607 1.41421 1.00000 1.41421 2.23607 + //- 2.23607 2.00000 2.23607 + // + // However, the set consists of 21 members, so one item will be missing. + // Only the furthest points are candidates to be missing: + // + //- 24, 26, 33, 37, 53, 57, 64, 66 + // + //*** + + // Display the results + test.report() << "Find 20 nearest neighbors to point 45: (4,5)...\n"; + std::deque idxs = results.first; + std::deque dists = results.second; test.report() << "idxs = {"; @@ -78,5 +136,5 @@ { test.report() << idxs[0]; - for (unsigned int idx = 1; idx < idxs.size(); ++idx) + for (std::size_t idx = 1; idx < idxs.size(); ++idx) { test.report() << ", " << idxs[idx]; @@ -91,5 +149,5 @@ { test.report() << dists[0]; - for (unsigned int idx = 1; idx < idxs.size(); ++idx) + for (std::size_t idx = 1; idx < idxs.size(); ++idx) { test.report() << ", " << dists[idx]; @@ -98,5 +156,77 @@ test.report() << "}\n"; - return true; + + // Check the results + bool passedAll = true; + bool check; + + test.report() << "Check that index and distance set sizes match... "; + check = (idxs.size() == dists.size()); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + test.report() << "Check that we found 20 neighbors... "; + check = (idxs.size() == 20); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + // Check nearest elements + { + IndexT f[] = { 25, + 34, 35, 36, + 43, 44, 45, 46, 47, + 54, 55, 56, + 65}; + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 13 out of 13 near neighbors are found + test.report() << "Check that all 13 of 13 nearest neighbors are " + << "found... "; + check = (present == 13); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + // Check furthest elements + { + IndexT f[] = { 24, 26, + 33, 37, + + 53, 57, + 64, 66}; + + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 7 out of 8 furthest neighbors are found + test.report() << "Check that only 7 of 8 furthest neighbors are " + << "found... "; + check = (present == 7); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + return passedAll; EXCEPTION_RETHROW; @@ -106,229 +236,1010 @@ // and only if the test passes. //< - -private: }; -////***************************************************************************** -//// FUNCTOR: testManhattan -////***************************************************************************** -//template -//class testManhattan : public TestCase::TestStep -//{ -//public: -// testManhattan() -// : TestCase::TestStep(typeid(theMetric).name()) -// , theMetric() -// { -// } -// //> -// //< -// -// bool approx_equal(ReturnT a, ReturnT b) const -// { -// double absTolI = std::numeric_limits::epsilon(); -// double absTolO = std::numeric_limits::epsilon(); -// -// double absTol = (absTolI > absTolO) ? absTolI : absTolO; -// -// ReturnT inMax = (std::abs(a) > std::abs(b)) -// ? std::abs(a) -// : std::abs(b); -// -// inMax = (inMax > static_cast(1.0)) -// ? inMax -// : static_cast(1.0); -// -// return (std::abs(a - b) <= absTol * inMax); -// } -// -// bool operator()(TestCase& test) const -// { -// EXCEPTION_TRY("Damkjer::testManhattan::operator(TestCase&)"); -// -// PointT a; -// a.push_back(static_cast(0.3)); -// a.push_back(static_cast(0.5)); -// -// PointT b; -// b.push_back(static_cast(0.7)); -// b.push_back(static_cast(0.8)); -// -// ReturnT fromMetric = theMetric(a, b); -// -// //*** -// // Expected value is |0.7-0.3|+|0.8-0.5| -// // 0.4+0.3 -// // 0.7 -// //*** -// bool passed = approx_equal(fromMetric, static_cast(0.7)); -// -// test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" -// << "Expected result : " -// << std::setprecision(12) << static_cast(0.7) << "\n"; -// -// return passed; -// -// EXCEPTION_RETHROW; -// } -// //> The parentheses operator represents the body of the test step -// // function. It will perform the necessary evaluation and return true if -// // and only if the test passes. -// //< -// -//private: -// ManhattanDistance theMetric; -// //> -// //< -//}; -// -////***************************************************************************** -//// FUNCTOR: testChebyshev -////***************************************************************************** -//template -//class testChebyshev : public TestCase::TestStep -//{ -//public: -// testChebyshev() -// : TestCase::TestStep(typeid(theMetric).name()) -// , theMetric() -// { -// } -// //> -// //< -// -// bool approx_equal(ReturnT a, ReturnT b) const -// { -// double absTolI = std::numeric_limits::epsilon(); -// double absTolO = std::numeric_limits::epsilon(); -// -// double absTol = (absTolI > absTolO) ? absTolI : absTolO; -// -// ReturnT inMax = (std::abs(a) > std::abs(b)) -// ? std::abs(a) -// : std::abs(b); -// -// inMax = (inMax > static_cast(1.0)) -// ? inMax -// : static_cast(1.0); -// -// return (std::abs(a - b) <= absTol * inMax); -// } -// -// bool operator()(TestCase& test) const -// { -// EXCEPTION_TRY("Damkjer::testChebyshev::operator(TestCase&)"); -// -// PointT a; -// a.push_back(static_cast(0.3)); -// a.push_back(static_cast(0.5)); -// -// PointT b; -// b.push_back(static_cast(0.7)); -// b.push_back(static_cast(0.8)); -// -// ReturnT fromMetric = theMetric(a, b); -// -// //*** -// // Expected value is max(|0.7-0.3|,|0.8-0.5|) -// // max(0.4,0.3) -// // 0.4 -// //*** -// bool passed = approx_equal(fromMetric, static_cast(0.4)); -// -// test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" -// << "Expected result : " -// << std::setprecision(12) << static_cast(0.4) << "\n"; -// -// return passed; -// -// EXCEPTION_RETHROW; -// } -// //> The parentheses operator represents the body of the test step -// // function. It will perform the necessary evaluation and return true if -// // and only if the test passes. -// //< -// -//private: -// ChebyshevDistance theMetric; -// //> -// //< -//}; -// -////***************************************************************************** -//// FUNCTOR: testMinkowski -////***************************************************************************** -//template -//class testMinkowski : public TestCase::TestStep -//{ -//public: -// testMinkowski() -// : TestCase::TestStep(typeid(theMetric).name()) -// , theMetric(2) -// { -// } -// //> -// //< -// -// bool approx_equal(ReturnT a, ReturnT b) const -// { -// double absTolI = std::numeric_limits::epsilon(); -// double absTolO = std::numeric_limits::epsilon(); -// -// double absTol = (absTolI > absTolO) ? absTolI : absTolO; -// -// ReturnT inMax = (std::abs(a) > std::abs(b)) -// ? std::abs(a) -// : std::abs(b); -// -// inMax = (inMax > static_cast(1.0)) -// ? inMax -// : static_cast(1.0); -// -// return (std::abs(a - b) <= absTol * inMax); -// } -// -// bool operator()(TestCase& test) const -// { -// EXCEPTION_TRY("Damkjer::testMinkowski::operator(TestCase&)"); -// -// PointT a; -// a.push_back(static_cast(0.3)); -// a.push_back(static_cast(0.5)); -// -// PointT b; -// b.push_back(static_cast(0.7)); -// b.push_back(static_cast(0.8)); -// -// ReturnT fromMetric = theMetric(a, b); -// -// //*** -// // Expected value is sqrt((0.7-0.3)*(0.7-0.3)+(0.8-0.5)*(0.8-0.5)) -// // sqrt(0.4*0.4+0.3*0.3) -// // sqrt(0.16+0.09) -// // sqrt(0.25) -// // 0.5 -// //*** -// bool passed = approx_equal(fromMetric, static_cast(0.5)); -// -// test.report() << "Value from Euclidean Metric: " << std::setprecision(12) << fromMetric << "\n" -// << "Expected result : " -// << std::setprecision(12) << static_cast(0.5) << "\n"; -// -// return passed; -// -// EXCEPTION_RETHROW; -// } -// //> The parentheses operator represents the body of the test step -// // function. It will perform the necessary evaluation and return true if -// // and only if the test passes. -// //< -// -//private: -// MinkowskiDistance theMetric; -// //> -// //< -//}; -// +//***************************************************************************** +// FUNCTOR: testEuclideanRnn +//***************************************************************************** +template +class testEuclideanRnn : public TestCase::TestStep +{ +public: + testEuclideanRnn() + : TestCase::TestStep((std::string( + "radially nearest-neighbor algorithm in Euclidean " + "space for points of type: ") + + typeid(PointT).name())) + { + } + //> + //< + + bool operator()(TestCase& test) const + { + EXCEPTION_TRY("Damkjer::testEuclideanRnn::operator(TestCase&)"); + + typedef typename PointT::value_type ValueT; + typedef EuclideanDistance MetricT; + typedef typename MetricT::return_type DistT; + + //*** + // Set up a 2D point layout on a regular grid as follows: + // + //- (0,0) (0,1) (0,2) ... (0,9) + //- (1,0) (1,1) (1,2) ... (1,9) + //- . . . . . + //- . . . . . + //- . . . . . + //- (9,0) (9,1) (9,2) ... (9,9) + // + // Make sure points are created in top-left to bottom-right row-major + // order to force known indices: + // + //- 0 1 2 ... 9 + //- 10 11 12 ... 19 + //- . . . . . + //- . . . . . + //- . . . . . + //- 90 91 92 ... 99 + // + //*** + + std::deque data; + + for (unsigned int row = 0; row < 10; ++row) + { + for (unsigned int col = 0; col < 10; ++col) + { + PointT pt; + pt.push_back(static_cast(row)); + pt.push_back(static_cast(col)); + data.push_back(pt); + } + } + + // Create the spatially indexed database + typedef VpTree VpTreeT; + + VpTreeT database(data); + typedef typename VpTreeT::IndexT IndexT; + typedef typename VpTreeT::SearchResultsT SearchResultsT; + + // Perform a search for the nearest neighbors to point 45 within 3 units. + ValueT radius = 3; + SearchResultsT results = database.rnn(data[45], radius); + + //*** + // In Euclidean space, the results should belong to the following set: + // + //- 15 + //- 23 24 25 26 27 + //- 33 34 35 36 37 + //- 42 43 44 45 46 47 48 + //- 53 54 55 56 57 + //- 63 64 65 66 67 + //- 75 + // + // With distances: + // + //- 3.00000 + //- 2.82843 2.23607 2.00000 2.23607 2.82843 + //- 2.23607 1.41421 1.00000 1.41421 2.23607 + //- 3.00000 2.00000 1.00000 0.00000 1.00000 2.00000 3.00000 + //- 2.23607 1.41421 1.00000 1.41421 2.23607 + //- 2.82843 2.23607 2.00000 2.23607 2.82843 + //- 3.00000 + // + //*** + + // Display the results + test.report() << "Find nearest neighbors to point 45 (4,5) within 3 " + << "units...\n"; + std::deque idxs = results.first; + std::deque dists = results.second; + + test.report() << "idxs = {"; + + if (!idxs.empty()) + { + test.report() << idxs[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << idxs[idx]; + } + } + + test.report() << "}\n"; + + test.report() << "dists = {"; + + if (!idxs.empty()) + { + test.report() << dists[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << dists[idx]; + } + } + + test.report() << "}\n"; + + // Check the results + bool passedAll = true; + bool check; + + test.report() << "Check that index and distance set sizes match... "; + check = (idxs.size() == dists.size()); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + test.report() << "Check that we found 29 neighbors... "; + check = (idxs.size() == 29); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + // Check nearest elements + { + IndexT f[] = { 15, + 23, 24, 25, 26, 27, + 33, 34, 35, 36, 37, + 42, 43, 44, 45, 46, 47, 48, + 53, 54, 55, 56, 57, + 63, 64, 65, 66, 67, + 75}; + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 13 out of 13 near neighbors are found + test.report() << "Check that all 29 nearest neighbors are " + << "found... "; + check = (present == 29); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + // Check distances + { + check = true; + // Check that no distance exceeds the search reach + test.report() << "Check that no distance exceeds the search " + << "reach... "; + + for (std::size_t dist = dists.size(); dist --> 0;) + { + check &= (dists[dist] <= radius); + } + + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + return passedAll; + + EXCEPTION_RETHROW; + } + //> The parentheses operator represents the body of the test step + // function. It will perform the necessary evaluation and return true if + // and only if the test passes. + //< +}; + +//***************************************************************************** +// FUNCTOR: testManhattanKnn +//***************************************************************************** +template +class testManhattanKnn : public TestCase::TestStep +{ +public: + testManhattanKnn() + : TestCase::TestStep((std::string( + "k nearest-neighbor algorithm in Manhattan space " + "for points of type: ") + + typeid(PointT).name())) + { + } + //> + //< + + bool operator()(TestCase& test) const + { + EXCEPTION_TRY("Damkjer::testManhattanKnn::operator(TestCase&)"); + + typedef typename PointT::value_type ValueT; + typedef ManhattanDistance MetricT; + typedef typename MetricT::return_type DistT; + + //*** + // Set up a 2D point layout on a regular grid as follows: + // + //- (0,0) (0,1) (0,2) ... (0,9) + //- (1,0) (1,1) (1,2) ... (1,9) + //- . . . . . + //- . . . . . + //- . . . . . + //- (9,0) (9,1) (9,2) ... (9,9) + // + // Make sure points are created in top-left to bottom-right row-major + // order to force known indices: + // + //- 0 1 2 ... 9 + //- 10 11 12 ... 19 + //- . . . . . + //- . . . . . + //- . . . . . + //- 90 91 92 ... 99 + // + //*** + + std::deque data; + + for (unsigned int row = 0; row < 10; ++row) + { + for (unsigned int col = 0; col < 10; ++col) + { + PointT pt; + pt.push_back(static_cast(row)); + pt.push_back(static_cast(col)); + data.push_back(pt); + } + } + + // Create the spatially indexed database + typedef VpTree VpTreeT; + + VpTreeT database(data); + typedef typename VpTreeT::IndexT IndexT; + typedef typename VpTreeT::SearchResultsT SearchResultsT; + + // Perform a search for the 20 nearest neighbors to point 45. + SearchResultsT results = database.knn(data[45], 20); + + //*** + // In Manhattan space, the results should belong to the following set: + // + //- 15 + //- 24 25 26 + //- 33 34 35 36 37 + //- 42 43 44 45 46 47 48 + //- 53 54 55 56 57 + //- 64 65 66 + //- 75 + // + // With distances: + // + //- 3 + //- 3 2 3 + //- 3 2 1 2 3 + //- 3 2 1 0 1 2 3 + //- 3 2 1 2 3 + //- 3 2 3 + //- 3 + // + // However, the set consists of 25 members, so five items will be + // missing. Only the furthest points are candidates to be missing: + // + //- 15, 24, 26, 33, 37, 42, 48, 53, 57, 64, 66, 75 + // + //*** + + // Display the results + test.report() << "Find 20 nearest neighbors to point 45: (4,5)...\n"; + std::deque idxs = results.first; + std::deque dists = results.second; + + test.report() << "idxs = {"; + + if (!idxs.empty()) + { + test.report() << idxs[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << idxs[idx]; + } + } + + test.report() << "}\n"; + + test.report() << "dists = {"; + + if (!idxs.empty()) + { + test.report() << dists[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << dists[idx]; + } + } + + test.report() << "}\n"; + + // Check the results + bool passedAll = true; + bool check; + + test.report() << "Check that index and distance set sizes match... "; + check = (idxs.size() == dists.size()); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + test.report() << "Check that we found 20 neighbors... "; + check = (idxs.size() == 20); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + // Check nearest elements + { + IndexT f[] = { 25, + 34, 35, 36, + 43, 44, 45, 46, 47, + 54, 55, 56, + 65}; + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 13 out of 13 near neighbors are found + test.report() << "Check that all 13 of 13 nearest neighbors are " + << "found... "; + check = (present == 13); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + // Check furthest elements + { + IndexT f[] = { 15, + 24, 26, + 33, 37, + 42, 48, + 53, 57, + 64, 66, + 75}; + + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 7 out of 8 furthest neighbors are found + test.report() << "Check that only 7 of 8 furthest neighbors are " + << "found... "; + check = (present == 7); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + return passedAll; + + EXCEPTION_RETHROW; + } + //> The parentheses operator represents the body of the test step + // function. It will perform the necessary evaluation and return true if + // and only if the test passes. + //< +}; + +//***************************************************************************** +// FUNCTOR: testManhattanRnn +//***************************************************************************** +template +class testManhattanRnn : public TestCase::TestStep +{ +public: + testManhattanRnn() + : TestCase::TestStep((std::string( + "radially nearest-neighbor algorithm in Manhattan " + "space for points of type: ") + + typeid(PointT).name())) + { + } + //> + //< + + bool operator()(TestCase& test) const + { + EXCEPTION_TRY("Damkjer::testManhattanRnn::operator(TestCase&)"); + + typedef typename PointT::value_type ValueT; + typedef ManhattanDistance MetricT; + typedef typename MetricT::return_type DistT; + + //*** + // Set up a 2D point layout on a regular grid as follows: + // + //- (0,0) (0,1) (0,2) ... (0,9) + //- (1,0) (1,1) (1,2) ... (1,9) + //- . . . . . + //- . . . . . + //- . . . . . + //- (9,0) (9,1) (9,2) ... (9,9) + // + // Make sure points are created in top-left to bottom-right row-major + // order to force known indices: + // + //- 0 1 2 ... 9 + //- 10 11 12 ... 19 + //- . . . . . + //- . . . . . + //- . . . . . + //- 90 91 92 ... 99 + // + //*** + + std::deque data; + + for (unsigned int row = 0; row < 10; ++row) + { + for (unsigned int col = 0; col < 10; ++col) + { + PointT pt; + pt.push_back(static_cast(row)); + pt.push_back(static_cast(col)); + data.push_back(pt); + } + } + + // Create the spatially indexed database + typedef VpTree VpTreeT; + + VpTreeT database(data); + typedef typename VpTreeT::IndexT IndexT; + typedef typename VpTreeT::SearchResultsT SearchResultsT; + + // Perform a search for the nearest neighbors to point 45 within 3 units. + ValueT radius = 3; + SearchResultsT results = database.rnn(data[45], radius); + + //*** + // In Manhattan space, the results should belong to the following set: + // + //- 15 + //- 24 25 26 + //- 33 34 35 36 37 + //- 42 43 44 45 46 47 48 + //- 53 54 55 56 57 + //- 64 65 66 + //- 75 + // + // With distances: + // + //- 3 + //- 3 2 3 + //- 3 2 1 2 3 + //- 3 2 1 0 1 2 3 + //- 3 2 1 2 3 + //- 3 2 3 + //- 3 + // + //*** + + // Display the results + test.report() << "Find nearest neighbors to point 45 (4,5) within 3 " + << "units...\n"; + std::deque idxs = results.first; + std::deque dists = results.second; + + test.report() << "idxs = {"; + + if (!idxs.empty()) + { + test.report() << idxs[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << idxs[idx]; + } + } + + test.report() << "}\n"; + + test.report() << "dists = {"; + + if (!idxs.empty()) + { + test.report() << dists[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << dists[idx]; + } + } + + test.report() << "}\n"; + + // Check the results + bool passedAll = true; + bool check; + + test.report() << "Check that index and distance set sizes match... "; + check = (idxs.size() == dists.size()); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + test.report() << "Check that we found 25 neighbors... "; + check = (idxs.size() == 25); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + // Check nearest elements + { + IndexT f[] = { 15, + 24, 25, 26, + 33, 34, 35, 36, 37, + 42, 43, 44, 45, 46, 47, 48, + 53, 54, 55, 56, 57, + 64, 65, 66, + 75}; + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 13 out of 13 near neighbors are found + test.report() << "Check that all 25 nearest neighbors are " + << "found... "; + check = (present == 25); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + // Check distances + { + check = true; + // Check that no distance exceeds the search reach + test.report() << "Check that no distance exceeds the search " + << "reach... "; + + for (std::size_t dist = dists.size(); dist --> 0;) + { + check &= (dists[dist] <= radius); + } + + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + return passedAll; + + EXCEPTION_RETHROW; + } + //> The parentheses operator represents the body of the test step + // function. It will perform the necessary evaluation and return true if + // and only if the test passes. + //< +}; + +//***************************************************************************** +// FUNCTOR: testChebyshevKnn +//***************************************************************************** +template +class testChebyshevKnn : public TestCase::TestStep +{ +public: + testChebyshevKnn() + : TestCase::TestStep((std::string( + "k nearest-neighbor algorithm in Chebyshev space " + "for points of type: ") + + typeid(PointT).name())) + { + } + //> + //< + + bool operator()(TestCase& test) const + { + EXCEPTION_TRY("Damkjer::testManhattanKnn::operator(TestCase&)"); + + typedef typename PointT::value_type ValueT; + typedef ChebyshevDistance MetricT; + typedef typename MetricT::return_type DistT; + + //*** + // Set up a 2D point layout on a regular grid as follows: + // + //- (0,0) (0,1) (0,2) ... (0,9) + //- (1,0) (1,1) (1,2) ... (1,9) + //- . . . . . + //- . . . . . + //- . . . . . + //- (9,0) (9,1) (9,2) ... (9,9) + // + // Make sure points are created in top-left to bottom-right row-major + // order to force known indices: + // + //- 0 1 2 ... 9 + //- 10 11 12 ... 19 + //- . . . . . + //- . . . . . + //- . . . . . + //- 90 91 92 ... 99 + // + //*** + + std::deque data; + + for (unsigned int row = 0; row < 10; ++row) + { + for (unsigned int col = 0; col < 10; ++col) + { + PointT pt; + pt.push_back(static_cast(row)); + pt.push_back(static_cast(col)); + data.push_back(pt); + } + } + + // Create the spatially indexed database + typedef VpTree VpTreeT; + + VpTreeT database(data); + typedef typename VpTreeT::IndexT IndexT; + typedef typename VpTreeT::SearchResultsT SearchResultsT; + + // Perform a search for the 20 nearest neighbors to point 45. + SearchResultsT results = database.knn(data[45], 20); + + //*** + // In Chebyshev space, the results should belong to the following set: + // + //- 23 24 25 26 27 + //- 33 34 35 36 37 + //- 43 44 45 46 47 + //- 53 54 55 56 57 + //- 63 64 65 66 67 + // + // With distances: + // + //- 2 2 2 2 2 + //- 2 1 1 1 2 + //- 2 1 0 1 2 + //- 2 1 1 1 2 + //- 2 2 2 2 2 + // + // However, the set consists of 25 members, so five items will be + // missing. Only the furthest points are candidates to be missing: + // + //- 23, 24, 25, 26, 27, 33, 37, 43, 47, 53, 57, 63, 64, 65, 66, 67 + // + //*** + + // Display the results + test.report() << "Find 20 nearest neighbors to point 45: (4,5)...\n"; + std::deque idxs = results.first; + std::deque dists = results.second; + + test.report() << "idxs = {"; + + if (!idxs.empty()) + { + test.report() << idxs[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << idxs[idx]; + } + } + + test.report() << "}\n"; + + test.report() << "dists = {"; + + if (!idxs.empty()) + { + test.report() << dists[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << dists[idx]; + } + } + + test.report() << "}\n"; + + // Check the results + bool passedAll = true; + bool check; + + test.report() << "Check that index and distance set sizes match... "; + check = (idxs.size() == dists.size()); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + test.report() << "Check that we found 20 neighbors... "; + check = (idxs.size() == 20); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + // Check nearest elements + { + IndexT f[] = {34, 35, 36, + 44, 45, 46, + 54, 55, 56}; + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 9 out of 9 near neighbors are found + test.report() << "Check that all 9 of 9 nearest neighbors are " + << "found... "; + check = (present == 9); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + // Check furthest elements + { + IndexT f[] = {23, 24, 25, 26, 27, + 33, 37, + 43, 47, + 53, 57, + 63, 64, 65, 66, 67}; + + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 11 out of 16 furthest neighbors are found + test.report() << "Check that only 11 of 16 furthest neighbors are " + << "found... "; + check = (present == 11); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + return passedAll; + + EXCEPTION_RETHROW; + } + //> The parentheses operator represents the body of the test step + // function. It will perform the necessary evaluation and return true if + // and only if the test passes. + //< +}; + +//***************************************************************************** +// FUNCTOR: testChebyshevRnn +//***************************************************************************** +template +class testChebyshevRnn : public TestCase::TestStep +{ +public: + testChebyshevRnn() + : TestCase::TestStep((std::string( + "radially nearest-neighbor algorithm in Chebyshev " + "space for points of type: ") + + typeid(PointT).name())) + { + } + //> + //< + + bool operator()(TestCase& test) const + { + EXCEPTION_TRY("Damkjer::testChebyshevRnn::operator(TestCase&)"); + + typedef typename PointT::value_type ValueT; + typedef ChebyshevDistance MetricT; + typedef typename MetricT::return_type DistT; + + //*** + // Set up a 2D point layout on a regular grid as follows: + // + //- (0,0) (0,1) (0,2) ... (0,9) + //- (1,0) (1,1) (1,2) ... (1,9) + //- . . . . . + //- . . . . . + //- . . . . . + //- (9,0) (9,1) (9,2) ... (9,9) + // + // Make sure points are created in top-left to bottom-right row-major + // order to force known indices: + // + //- 0 1 2 ... 9 + //- 10 11 12 ... 19 + //- . . . . . + //- . . . . . + //- . . . . . + //- 90 91 92 ... 99 + // + //*** + + std::deque data; + + for (unsigned int row = 0; row < 10; ++row) + { + for (unsigned int col = 0; col < 10; ++col) + { + PointT pt; + pt.push_back(static_cast(row)); + pt.push_back(static_cast(col)); + data.push_back(pt); + } + } + + // Create the spatially indexed database + typedef VpTree VpTreeT; + + VpTreeT database(data); + typedef typename VpTreeT::IndexT IndexT; + typedef typename VpTreeT::SearchResultsT SearchResultsT; + + // Perform a search for the nearest neighbors to point 45 within 3 units. + ValueT radius = 3; + SearchResultsT results = database.rnn(data[45], radius); + + //*** + // In Chebyshev space, the results should belong to the following set: + // + //- 12 13 14 15 16 17 18 + //- 22 23 24 25 26 27 28 + //- 32 33 34 35 36 37 38 + //- 42 43 44 45 46 47 48 + //- 52 53 54 55 56 57 58 + //- 62 63 64 65 66 67 68 + //- 72 73 74 75 76 77 78 + // + // With distances: + // + //- 3 3 3 3 3 3 3 + //- 3 2 2 2 2 2 3 + //- 3 2 1 1 1 2 3 + //- 3 2 1 0 1 2 3 + //- 3 2 1 1 1 2 3 + //- 3 2 2 2 2 2 3 + //- 3 3 3 3 3 3 3 + // + //*** + + // Display the results + test.report() << "Find nearest neighbors to point 45 (4,5) within 3 " + << "units...\n"; + std::deque idxs = results.first; + std::deque dists = results.second; + + test.report() << "idxs = {"; + + if (!idxs.empty()) + { + test.report() << idxs[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << idxs[idx]; + } + } + + test.report() << "}\n"; + + test.report() << "dists = {"; + + if (!idxs.empty()) + { + test.report() << dists[0]; + for (std::size_t idx = 1; idx < idxs.size(); ++idx) + { + test.report() << ", " << dists[idx]; + } + } + + test.report() << "}\n"; + + // Check the results + bool passedAll = true; + bool check; + + test.report() << "Check that index and distance set sizes match... "; + check = (idxs.size() == dists.size()); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + test.report() << "Check that we found 49 neighbors... "; + check = (idxs.size() == 49); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + + // Check nearest elements + { + IndexT f[] = {12, 13, 14, 15, 16, 17, 18, + 22, 23, 24, 25, 26, 27, 28, + 32, 33, 34, 35, 36, 37, 38, + 42, 43, 44, 45, 46, 47, 48, + 52, 53, 54, 55, 56, 57, 58, + 62, 63, 64, 65, 66, 67, 68, + 72, 73, 74, 75, 76, 77, 78}; + std::vector furthest(f, + f + sizeof(f)/sizeof(IndexT)); + + unsigned char present = 0; + typename std::deque::iterator pos; + + for (std::size_t nbr = furthest.size(); nbr --> 0;) + { + pos = find(idxs.begin(), idxs.end(), furthest[nbr]); + + if (pos != idxs.end()) ++present; + } + + // Check that 49 out of 49 near neighbors are found + test.report() << "Check that all 49 nearest neighbors are " + << "found... "; + check = (present == 49); + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + // Check distances + { + check = true; + // Check that no distance exceeds the search reach + test.report() << "Check that no distance exceeds the search " + << "reach... "; + + for (std::size_t dist = dists.size(); dist --> 0;) + { + check &= (dists[dist] <= radius); + } + + passedAll &= check; + test.report() << ((check) ? "[OK]" : "[FAILED]") << "\n"; + } + + return passedAll; + + EXCEPTION_RETHROW; + } + //> The parentheses operator represents the body of the test step + // function. It will perform the necessary evaluation and return true if + // and only if the test passes. + //< +}; + //***************************************************************************** // CONSTRUCTOR: TestVpTree::TestVpTree(int, char**) @@ -345,18 +1256,18 @@ typedef std::vector DblPtT; - typedef EuclideanDistance EuclidFltT; - typedef EuclideanDistance EuclidDblT; - typedef ManhattanDistance ManhattanFltT; - typedef ManhattanDistance ManhattanDblT; - typedef ChebyshevDistance ChebyshevFltT; - typedef ChebyshevDistance ChebyshevDblT; - typedef MinkowskiDistance MinkowskiDblT; - - registerStep(new testKnn()); - registerStep(new testKnn()); - registerStep(new testKnn()); - registerStep(new testKnn()); - registerStep(new testKnn()); - registerStep(new testKnn()); + registerStep(new testEuclideanKnn()); + registerStep(new testEuclideanKnn()); + registerStep(new testEuclideanRnn()); + registerStep(new testEuclideanRnn()); + registerStep(new testManhattanKnn()); + registerStep(new testManhattanKnn()); + registerStep(new testManhattanRnn()); + registerStep(new testManhattanRnn()); + registerStep(new testChebyshevKnn()); + registerStep(new testChebyshevKnn()); + registerStep(new testChebyshevRnn()); + registerStep(new testChebyshevRnn()); + + // Need to add radial tests. EXCEPTION_RETHROW; Index: Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.h =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.h (revision 10) +++ Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.h (revision 12) @@ -29,4 +29,7 @@ //> //< +private: + TestVpTree(const TestVpTree&); + TestVpTree& operator=(const TestVpTree&); }; Index: Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.vcxproj =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.vcxproj (revision 10) +++ Damkjer/Util/SpatialIndexing/VpTree/test/TestVpTree.vcxproj (revision 12) @@ -2,4 +2,12 @@ + + DebugOMP + Win32 + + + DebugOMP + x64 + Debug @@ -26,9 +34,4 @@ x64 - - - - {20fe2624-c64f-d61a-bd8f-1725a8e68a42} - @@ -39,4 +42,9 @@ + + + {20fe2624-c64f-d61a-bd8f-1725a8e68a42} + + Win32Proj @@ -48,5 +56,13 @@ true + + Application + true + + Application + true + + Application true @@ -74,5 +90,11 @@ + + + + + + @@ -95,5 +117,14 @@ call $(TargetPath) + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + call $(TargetPath) + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ @@ -132,4 +163,22 @@ Console + + + + + _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + Console + setlocal @@ -171,4 +220,21 @@ Console + + + + + _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + Console + setlocal @@ -327,4 +393,8 @@ true true + /wd4514 /wd4571 /wd4668 /wd4710 /wd4711 /wd4820 /wd4986 %(AdditionalOptions) + AnySuitable + true + Speed Index: Damkjer/Util/SpatialIndexing/VpTree/test/test_VpTree.cpp =================================================================== --- Damkjer/Util/SpatialIndexing/VpTree/test/test_VpTree.cpp (revision 10) +++ Damkjer/Util/SpatialIndexing/VpTree/test/test_VpTree.cpp (revision 12) @@ -14,5 +14,5 @@ //***************************************************************************** -#include "damkjerConfig.h" +#include "Util/Exception/Exception.h" #include "TestVpTree.h" Index: Damkjer/Util/Streams/BlockIndent.cpp =================================================================== --- Damkjer/Util/Streams/BlockIndent.cpp (revision 10) +++ Damkjer/Util/Streams/BlockIndent.cpp (revision 12) @@ -4,11 +4,14 @@ // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: This class performs the function of block-indenting a stream. -// It is a convenience manipulator based heavily on the code -// provided at: +// DESCRIPTION: +//> This class performs the function of block-indenting a stream. It is a +// convenience manipulator based heavily on the code provided at: // -// http://stackoverflow.com/questions/5280858/indenting-paragraph-with-cout +// http://stackoverflow.com/questions/5280858/indenting-paragraph-with-cout +//< // // LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -18,7 +21,7 @@ //***************************************************************************** +#include + #include "BlockIndent.h" - -#include namespace Damkjer @@ -26,18 +29,36 @@ //***************************************************************************** -// blockIndent static variable instantiation +// BlockIndent static variable instantiation //***************************************************************************** -const int blockIndent::INDENT_INDEX = std::ios_base::xalloc(); -std::deque blockIndent::INDENTS; +const int BlockIndent::soleIndentationIndex = std::ios_base::xalloc(); + //> The singular index into the stream buffer extensible iword array for the + // current indentation level. + //< + +std::deque BlockIndent::soleIndentationRegistry; + //> The singular indentation registry used to track block indentation + // levels. + //< //***************************************************************************** -// BlockIndent::operator() +// BlockIndent::operator()(std::ostream&) +//> Manipulate the given output stream with a block indentation style. This +// method provides a functor interface for operating on std::ostream +// objects. This function cannot be templatized, otherwise compilers will +// inline the method, thus exposing the private static variables on the +// class to the shared library interface. Further, this method is only valid +// for std::ostream objects since it manipulates the object's +// std::ios_base::iword database in an output streaming context. +// +// @param output The output stream to manipulate. +// @return The manipulated output stream. +//< //***************************************************************************** -Util_API std::ostream& blockIndent::operator()(std::ostream& output) const +Util_API std::ostream& BlockIndent::operator()(std::ostream& output) const { // Blocks should always start on a new line, but we don't always need a new // line to start a block. What to do? - output.iword(INDENT_INDEX) += theIndent; - INDENTS.push_front(theIndent); + output.iword(soleIndentationIndex) += theNumSpaces; + soleIndentationRegistry.push_front(theNumSpaces); return output; @@ -45,5 +66,10 @@ //***************************************************************************** -// endBlock +// endBlock(std::ostream&) +//> End the current block indentation in the specified output stream. +// +// @param output The output stream to modify. +// @return The modified output stream. +//< //***************************************************************************** Util_API std::ostream& endBlock(std::ostream& output) @@ -53,9 +79,9 @@ // output << "\n"; - if (!blockIndent::INDENTS.empty()) + if (!BlockIndent::soleIndentationRegistry.empty()) { - int decr = blockIndent::INDENTS.front(); - blockIndent::INDENTS.pop_front(); - output.iword(blockIndent::INDENT_INDEX) -= decr; + int decr = BlockIndent::soleIndentationRegistry.front(); + BlockIndent::soleIndentationRegistry.pop_front(); + output.iword(BlockIndent::soleIndentationIndex) -= decr; } Index: Damkjer/Util/Streams/BlockIndent.h =================================================================== --- Damkjer/Util/Streams/BlockIndent.h (revision 10) +++ Damkjer/Util/Streams/BlockIndent.h (revision 12) @@ -4,78 +4,94 @@ // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: blockIndent +// DESCRIPTION: +//> The interface definition for the block indentation output stream +// manipulator. +//< +// +// LIMITATIONS: +//> No known limitations. +//< +// +// SOFTWARE HISTORY: +//> 2013-JUL-26 K. Damkjer +// Initial Coding. +//< +//***************************************************************************** + +#ifndef Damkjer_BlockIndent_HEADER +#define Damkjer_BlockIndent_HEADER + +#if _MSC_VER +#pragma warning(push, 0) +#endif + +#include +#include + +#if _MSC_VER +#pragma warning(pop) +#endif + +#include "Util/UtilAPI.h" +#include "Util/Streams/ManipulatorBase.h" + +namespace Damkjer +{ + +Util_API std::ostream& endBlock(std::ostream&); + //> End the current block indentation in the specified output stream. + //< + +//***************************************************************************** +// FUNCTOR: BlockIndent +//> An output stream manipulator for performing block indentation. // // This class performs the function of block-indenting a stream. It is a // convenience manipulator based heavily on the code provided at: // -// http://stackoverflow.com/questions/5280858/indenting-paragraph-with-cout -// -// LIMITATIONS: -// -// SOFTWARE HISTORY: -//> 2012-JUL-26 K. Damkjer -// Initial Coding. +// http://stackoverflow.com/questions/5280858/indenting-paragraph-with-cout //< //***************************************************************************** - -#ifndef BlockIndent_HEADER -#define BlockIndent_HEADER - -#include -#include - -#include "Util/UtilAPI.h" -#include "ManipulatorBase.h" - -namespace Damkjer -{ - -//***************************************************************************** -// FUNCTOR: blockIndent -//***************************************************************************** -class blockIndent : public ManipulatorBase +class BlockIndent : public ManipulatorBase { public: - Util_API explicit blockIndent(long indent = 3) - : ManipulatorBase() - , theIndent(indent) + Util_API explicit BlockIndent(long indent = 3) + : ManipulatorBase() + , theNumSpaces(indent) { } - //> + //> Instantiate a block indentation manipulator with a number of spaces + // to indent. + // + // @param indent The number of spaces to indent. Defaults to 3. //< Util_API std::ostream& operator()(std::ostream&) const; - //> This method provides a functor interface for operating on - // std::ostream objects. This function cannot be templatized, otherwise - // compilers will inline the method, thus exposing the private static - // variables on the class to the shared library interface. Further, this - // method is only valid for std::ostream objects since it manipulates - // the object's std::ios_base::iword database in an output streaming - // context. + //> Manipulate the given output stream with a block indentation style. //< - static int index() { return INDENT_INDEX; } - //> + Util_API static int index() { return soleIndentationIndex; } + //> The index for the indentation size in the stream buffer extensible + // iword array. + // + // @return The indentation index. //< private: - blockIndent(const blockIndent&); - blockIndent& operator=(const blockIndent&); + long theNumSpaces; + //> The number of spaces to indent this block. + //< + + static const int soleIndentationIndex; + //> The singular index into the stream buffer extensible iword array for + // the current indentation level. + //< + + static std::deque soleIndentationRegistry; + //> The singular indentation registry used to track block indentation + // levels. + //< friend Util_API std::ostream& endBlock(std::ostream&); - //> - //< - - static const int INDENT_INDEX; - //> - //< - - static std::deque INDENTS; - //> - //< - - const long theIndent; - //> - //< }; Index: Damkjer/Util/Streams/FormatFilter.cpp =================================================================== --- Damkjer/Util/Streams/FormatFilter.cpp (revision 10) +++ Damkjer/Util/Streams/FormatFilter.cpp (revision 12) @@ -4,7 +4,11 @@ // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: -// -// LIMITATIONS: +// DESCRIPTION: +//> The class implementation for the output format filter. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -14,29 +18,40 @@ //***************************************************************************** -#include "damkjerConfig.h" +#include + +#include "Util/Exception/Exception.h" + +#include "BlockIndent.h" #include "FormatFilter.h" -#include "BlockIndent.h" - -#include namespace Damkjer { //***************************************************************************** -// FormatFilter static variable instantiation -//***************************************************************************** -const int FormatFilter::LINE_WIDTH_INDEX = std::ios_base::xalloc(); - -//***************************************************************************** -// FormatFilter::FormatFilter -//***************************************************************************** -FormatFilter::FormatFilter(std::ostream& output, long lineWidth) - : theDestination(output) +// FormatFilter::soleLineWidthIndex +//> The index for the line width in the stream buffer extensible iword array. +//< +//***************************************************************************** +const int +FormatFilter::soleLineWidthIndex = std::ios_base::xalloc(); + +//***************************************************************************** +// FormatFilter::FormatFilter(std::ostream&, std::size_t) +//> Instantiate a format filter. +// +// @param output The stream to wrap for formatting. +// @param lineWidth The word-wrap line length. +//< +//***************************************************************************** +Util_API +FormatFilter::FormatFilter(std::ostream& output, std::size_t lineWidth) + : theCount(0) + , theDestination(output) , theDestinationBuf(output.rdbuf()) - , theCount(0) , theLineWidth(lineWidth) { - EXCEPTION_TRY("Damkjer::FormatFilter::FormatFilter(std::ostream&, long)"); - - theDestination.iword(widthIndex()) = lineWidth; + EXCEPTION_TRY("Damkjer::FormatFilter::FormatFilter(std::ostream&, " + "std::size_t)"); + + theDestination.iword(widthIndex()) = static_cast(lineWidth); theDestination.rdbuf(this); @@ -46,11 +61,14 @@ //***************************************************************************** // FormatFilter::~FormatFilter -//***************************************************************************** -Util_API FormatFilter::~FormatFilter() +//> Destruct the format filter and deallocate resources. +//< +//***************************************************************************** +Util_API +FormatFilter::~FormatFilter() { if (!theBuffer.empty()) { // flush the buffer, if needed. - overflow(NULL); + overflow('\0'); } @@ -60,15 +78,33 @@ //***************************************************************************** // FormatFilter::overflow -//***************************************************************************** -Util_API std::streambuf::int_type FormatFilter::overflow(int_type c) +//> Format the stream with line-wrapping and block indentation. +// +// The overflow method is called automatically when streambuf internal +// buffers become full and flush their contents. This method basically +// implements a line-buffering stream buffer. +// +// The algorithm is: +// +// - Explicit end of line ("\r" or "\n"): we flush our buffer to the +// underlying stream's buffer, and set our record of the line length to 0. +// - An "alert" character: sent to the underlying stream without recording +// its length, since it doesn't normally affect the a appearance of the +// output. +// - Tab: treated as moving to the next tab stop, which is assumed as +// happening every tab_width characters. +// - Everything else: really basic buffering with word wrapping. We try to +// add the character to the buffer, and if it exceeds our line width, we +// search for the last space/tab in the buffer and break the line there. +// If there is no space/tab, we break the line at the limit. +// +// @param c The character to be placed into the controlled output stream. +// @return The put character. +//< +//***************************************************************************** +std::streambuf::int_type +FormatFilter::overflow(int_type c) { EXCEPTION_TRY("Damkjer::FormatFilter::overflow(int_type)"); -// long lineWidth = theDestination.iword(widthIndex()); - long blockIndent = theDestination.iword(blockIndent::index()); - long blockWidth = theLineWidth - blockIndent; - - const char* prefix = std::string(blockIndent, ' ').c_str(); - if (traits_type::eq_int_type(traits_type::eof(), c)) { @@ -76,10 +112,21 @@ } + std::streamsize bufferSize = static_cast(theBuffer.size()); + std::streamsize blockIndent = theDestination.iword(BlockIndent::index()); + std::size_t indentAsSize = static_cast(blockIndent); + std::size_t blockWidth = (theLineWidth > indentAsSize) + ? theLineWidth - indentAsSize + : 1; + + const char* prefix = std::string(indentAsSize, ' ').c_str(); + + char_type character = static_cast(c); + switch (c) { - case NULL: + case '\0': theCount = 0; theDestinationBuf->sputn(prefix, blockIndent); - theDestinationBuf->sputn(theBuffer.c_str(), theBuffer.size()); + theDestinationBuf->sputn(theBuffer.c_str(), bufferSize); theBuffer.clear(); return c; @@ -91,9 +138,9 @@ // buffer, and set our record of the line length to 0. //*** - - theBuffer += static_cast(c); + + theBuffer += character; theCount = 0; theDestinationBuf->sputn(prefix, blockIndent); - theDestinationBuf->sputn(theBuffer.c_str(), theBuffer.size()); + theDestinationBuf->sputn(theBuffer.c_str(), bufferSize + 1); theBuffer.clear(); return c; @@ -106,5 +153,5 @@ //*** - return theDestinationBuf->sputc(static_cast(c)); + return theDestinationBuf->sputc(character); case '\t': @@ -114,6 +161,6 @@ //*** - theBuffer += static_cast(c); - theCount += TAB_WIDTH - theCount % TAB_WIDTH; + theBuffer += character; + theCount += soleTabWidth - theCount % soleTabWidth; return c; @@ -128,27 +175,28 @@ if (theCount >= blockWidth) { - size_t wpos = theBuffer.find_last_of("\\/ \t"); - - if (wpos != string::npos) + std::size_t pos = theBuffer.find_last_of("\\/ \t"); + std::streamsize posAsStrmSz = static_cast(pos); + + if (pos != FilterString::npos) { theDestinationBuf->sputn(prefix, blockIndent); - switch (theBuffer[wpos]) + switch (theBuffer[pos]) { case '\\': case '/': - theDestinationBuf->sputn(theBuffer.c_str(), wpos+1); + theDestinationBuf->sputn(theBuffer.c_str(), posAsStrmSz+1); break; default: - theDestinationBuf->sputn(theBuffer.c_str(), wpos); + theDestinationBuf->sputn(theBuffer.c_str(), posAsStrmSz); } - theCount = theBuffer.size()-wpos-1; - theBuffer = string(theBuffer, wpos+1); + theCount = theBuffer.size()-pos-1; + theBuffer = FilterString(theBuffer, pos+1); } else { theDestinationBuf->sputn(prefix, blockIndent); - theDestinationBuf->sputn(theBuffer.c_str(), theBuffer.size()); + theDestinationBuf->sputn(theBuffer.c_str(), bufferSize); theBuffer.clear(); theCount = 0; @@ -158,5 +206,5 @@ } - theBuffer += static_cast(c); + theBuffer += character; ++theCount; @@ -168,11 +216,20 @@ //***************************************************************************** -// sline -//***************************************************************************** -Util_API std::ostream& sline(std::ostream& output) +// sline(std::ostream&) +//> Insert a line of hyphen ('-') characters into the argument stream +// creating the appearance of a single horizontal line. +// +// @param output The stream to be updated. +// @return The updated stream. +//< +//***************************************************************************** +Util_API +std::ostream& +sline(std::ostream& output) { EXCEPTION_TRY("Damkjer::sline(std::ostream&)"); - long lineWidth = output.iword(FormatFilter::widthIndex()); + std::size_t lineWidth = static_cast( + output.iword(FormatFilter::widthIndex())); if (lineWidth == 0) @@ -182,7 +239,7 @@ } - long blockIndent = output.iword(blockIndent::index()); - long blockWidth = lineWidth - blockIndent; -// long blockWidth = (40 > lineWidth - blockIndent) ? 40 : lineWidth - blockIndent; + std::size_t blockIndent = static_cast( + output.iword(BlockIndent::index())); + std::size_t blockWidth = lineWidth - blockIndent; std::string line(blockWidth, '-'); @@ -196,11 +253,20 @@ //***************************************************************************** -// dline -//***************************************************************************** -Util_API std::ostream& dline(std::ostream& output) +// dline(std::ostream&) +//> Insert a line of equals ('=') characters into the argument stream +// creating the appearance of a double horizontal line. +// +// @param output The stream to be updated. +// @return The updated stream. +//< +//***************************************************************************** +Util_API +std::ostream& +dline(std::ostream& output) { EXCEPTION_TRY("Damkjer::dline(std::ostream&)"); - long lineWidth = output.iword(FormatFilter::widthIndex()); + std::size_t lineWidth = static_cast( + output.iword(FormatFilter::widthIndex())); if (lineWidth == 0) @@ -210,7 +276,7 @@ } - long blockIndent = output.iword(blockIndent::index()); - long blockWidth = lineWidth - blockIndent; -// long blockWidth = (40 > lineWidth - blockIndent) ? 40 : lineWidth - blockIndent; + std::size_t blockIndent = static_cast( + output.iword(BlockIndent::index())); + std::size_t blockWidth = lineWidth - blockIndent; std::string line(blockWidth, '='); Index: Damkjer/Util/Streams/FormatFilter.h =================================================================== --- Damkjer/Util/Streams/FormatFilter.h (revision 10) +++ Damkjer/Util/Streams/FormatFilter.h (revision 12) @@ -4,19 +4,23 @@ // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: +// DESCRIPTION: +//> The interface definition for the output format filter. +//< // -// LIMITATIONS: +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: -//> 2012-AUG-04 K. Damkjer +//> 2013-AUG-04 K. Damkjer // Initial Coding. //< //***************************************************************************** -#ifndef ConsoleOutput_HEADER -#define ConsoleOutput_HEADER +#ifndef Damkjer_FormatFilter_HEADER +#define Damkjer_FormatFilter_HEADER -#include -#include +#include // HASA std::ostream interface and data member. +#include // ISA std::streambuf derivative. #include "Util/UtilAPI.h" @@ -27,54 +31,50 @@ //***************************************************************************** // CLASS: FormatFilter +//> An output stream filter to produce line-wrapped and block-indented text. +//< //***************************************************************************** class FormatFilter : public std::streambuf { public: - explicit FormatFilter(std::ostream&, long lineWidth = 79); - //> Create a block indent stream buffer. + Util_API explicit FormatFilter(std::ostream&, std::size_t lineWidth = 79); + //> Instantiate a format filter. //< Util_API virtual ~FormatFilter(); - //> Free resources allocated by this clas. + //> Destruct the format filter and deallocate resources. //< - static int widthIndex() { return LINE_WIDTH_INDEX; } + Util_API static int widthIndex() { return soleLineWidthIndex; } + //> The index for the line width in the stream buffer extensible iword + // array. + // + // @return The line width index. + //< private: - FormatFilter(const FormatFilter&); - FormatFilter& operator=(const FormatFilter&); - - static const int LINE_WIDTH_INDEX; - //> + FormatFilter(); + //> Explicitly disable the compiler-generated default constructor. No + // definition provided. //< - static const int TAB_WIDTH = 8; - //> Define tab width as 8 spaces. + FormatFilter(const FormatFilter&); + //> Explicitly disable the compiler-generated copy constructor. No + // definition provided. //< - Util_API int_type overflow(int_type); - //> This method basically implements a line-buffering stream buffer. + FormatFilter& operator=(const FormatFilter&); + //> Explicitly disable the compiler-generated assignment operator. No + // definition provided. // - // The algorithm is: - // - // - Explicit end of line ("\r" or "\n"): we flush our buffer to the - // underlying stream's buffer, and set our record of the line length - // to 0. - // - // - An "alert" character: sent to the underlying stream without - // recording its length, since it doesn't normally affect the a - // appearance of the output. - // - // - Tab: treated as moving to the next tab stop, which is assumed as - // happening every tab_width characters. - // - // - Everything else: really basic buffering with word wrapping. We try - // to add the character to the buffer, and if it exceeds our line - // width, we search for the last space/tab in the buffer and break - // the line there. If there is no space/tab, we break the line at the - // limit. + // @return The updated left-hand side when not disabled. //< - typedef std::basic_string string; + int_type overflow(int_type); + //> Format the stream with line-wrapping and block indentation. + //< + + typedef std::basic_string FilterString; + //> The current count of characters in the block. + //< std::size_t theCount; @@ -83,5 +83,5 @@ std::ostream& theDestination; - //> + //> The destination stream for formatted stream data. //< @@ -90,15 +90,31 @@ //< - string theBuffer; + FilterString theBuffer; //> The actual buffer contents. //< - long theLineWidth; - //> + std::size_t theLineWidth; + //> The current formatted line width. + //< + + static const int soleLineWidthIndex; + //> The index for the line width in the stream buffer extensible iword + // array. + //< + + static const int soleTabWidth = 8; + //> Define tab width as 8 spaces. //< }; Util_API std::ostream& sline(std::ostream&); + //> Insert a line of hyphen ('-') characters into the argument stream + // creating the appearance of a single horizontal line. + //< + Util_API std::ostream& dline(std::ostream&); + //> Insert a line of equals ('=') characters into the argument stream + // creating the appearance of a double horizontal line. + //< } Index: Damkjer/Util/Streams/ManipulatorBase.h =================================================================== --- Damkjer/Util/Streams/ManipulatorBase.h (revision 9) +++ Damkjer/Util/Streams/ManipulatorBase.h (revision 12) @@ -4,21 +4,20 @@ // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: ManipulatorBase +// DESCRIPTION: +//> Base class interface definition for stream manipulators. +//< // -// ManipulatorBase is intended to provide the templated base class for -// stream manipulators modeled on the "Curiously Recurring Template Pattern" -// idiom. This idiom provides a simple interface for stream manipulators to -// be called with anonymous objects on input and output streams. -// -// LIMITATIONS: +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: -//> 2012-Aug-03 K. Damkjer +//> 2013-AUG-03 K. Damkjer // Initial Coding. //< //***************************************************************************** -#ifndef ManipulatorBase_HEADER -#define ManipulatorBase_HEADER +#ifndef Damkjer_ManipulatorBase_HEADER +#define Damkjer_ManipulatorBase_HEADER namespace Damkjer @@ -27,16 +26,32 @@ //***************************************************************************** // CLASS: ManipulatorBase +//> A template base class for stream manipulators. This class is modeled on +// the "Curiously Recurring Template Pattern". This pattern provides a +// simple interface for stream manipulators to be called with anonymous +// objects on input and output streams. It is an example of "static +// polymorphism". +// +// @tparam ManipulatorT The stream manipulator type. +//< //***************************************************************************** -template +template class ManipulatorBase { public: - template - Stream& operator()(Stream& stream) const + template + StreamT& operator()(StreamT& stream) const { // call Manipulator::operator() - static_cast(*this)(stream); + static_cast(*this)(stream); return stream; } + //> Invoke the ManipulatorT functor on the stream. The function operator + // allows manipulators derived from ManipulatorBase to behave as + // functions with state. + // + // @tparam StreamT The stream type. + // @param stream The stream to be manipulated. + // @return The manipulated stream. + //< }; @@ -44,9 +59,18 @@ //***************************************************************************** -// FUNCTION: operator<<(Ostream&, const ManipulatorBase&) +// FUNCTION: operator<<(OstreamT&, const ManipulatorBase&) +//> Manipulate an output stream with a manipulator via stream insertion. +// +// @tparam OstreamT The output stream type. +// @tparam ManipulatorT The output stream manipulator type. +// @param outputStream The output stream to be manipulated. +// @param manipulate The output stream manipulator functor. +// @return The manipulated output stream. +//< //***************************************************************************** -template -Ostream& operator<<(Ostream& outputStream, - const Damkjer::ManipulatorBase& manipulate) +template +inline OstreamT& +operator<<(OstreamT& outputStream, + const Damkjer::ManipulatorBase& manipulate) { return manipulate(outputStream); @@ -54,9 +78,18 @@ //***************************************************************************** -// FUNCTION: operator>>(Istream&, const ManipulatorBase&) +// FUNCTION: operator>>(IstreamT&, const ManipulatorBase&) +//> Manipulate an input stream with a manipulator via stream extraction. +// +// @tparam IstreamT The input stream type. +// @tparam ManipulatorT The input stream manipulator type. +// @param inputStream The input stream to be manipulated. +// @param manipulate The input stream manipulator functor. +// @return The manipulated input stream. +//< //***************************************************************************** -template -Istream& operator>>(Istream& inputStream, - const Damkjer::ManipulatorBase& manipulate) +template +inline IstreamT& +operator>>(IstreamT& inputStream, + const Damkjer::ManipulatorBase& manipulate) { return manipulate(inputStream); Index: Damkjer/Util/UnitTest/TestCase.cpp =================================================================== --- Damkjer/Util/UnitTest/TestCase.cpp (revision 10) +++ Damkjer/Util/UnitTest/TestCase.cpp (revision 12) @@ -1,10 +1,14 @@ //***************************************************************************** -// FILE: TestCase.h +// FILE: TestCase.cpp // // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: -// -// LIMITATIONS: +// DESCRIPTION: +//> The class implementation for unit test cases. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -16,44 +20,70 @@ #include #include - -#include "damkjerConfig.h" +#include + +#include "Util/Exception/Exception.h" +#include "Util/Streams/BlockIndent.h" + #include "TestCase.h" -#include "Util/Streams/BlockIndent.h" - namespace Damkjer { //***************************************************************************** -// TestCase::TestCase -//***************************************************************************** -Util_API TestCase::TestCase(int argc, char** argv, +// TestCase::TestCase(int, char**, const std::string&, const std::string&, +// const std::string&, std::ostream&) +//> Intialize a test case with required information. +// +// This constructor sets the name, ID, and description for the unit test +// case. It also wraps an output stream with a report stream to easily +// redirect and format test logs. +// +// @param argc The command-line argument count. +// @param argv The command-line arguments. +// @param caseName The test case descriptive name. +// @param caseID The test case identifier. +// @param caseDescription The test case verbose description. +// @param reportStream The test case report stream. Defaults to standard +// log output. +//< +//***************************************************************************** +Util_API +TestCase::TestCase(int argc, + char** argv, const std::string& caseName, const std::string& caseID, const std::string& caseDescription, - std::ostream& reportStream) - : theArgc(argc) - , theArgv(argv) + std::ostream& reportStream) + : theStartTime() , theCaseName(caseName) , theCaseID(caseID) , theCaseDescription(caseDescription) , theReportStream(reportStream) + , theStreamFormatter(reportStream) + , theArgv(argv) , theDetailsIndent(0) - , theStartTime() + , theArgc(argc) , theStepCount(0) - , theStreamFormatter(reportStream) -{ -} - -//***************************************************************************** -// TestCase::argv -//***************************************************************************** -Util_API std::string TestCase::argv(int i) const +{ +} + +//***************************************************************************** +// TestCase::argv(int) +//> The requested command line argument, converted to a string. +// +// @param index the index of the desired command line argument. +// @return the requested command line argument as a std::string. +// @throw OutOfRange when the reqested argument is outside the range of +// available arguments. +//< +//***************************************************************************** +Util_API +std::string TestCase::argv(int index) const { EXCEPTION_TRY("Damkjer::TestCase::argv(int)"); - if (i >= 0 && i < theArgc) + if (index >= 0 && index < theArgc) { - return theArgv[i]; + return theArgv[index]; } @@ -67,6 +97,6 @@ msg << "Error encountered while retrieving an argument vector (argv) " << "element.\n\n" - << "Unable to access the requested element (" << i << ") because it is " - << "outside the valid bounds of [0, " << theArgc << ")."; + << "Unable to access the requested element (" << index << ") because " + << "it is outside the valid bounds of [0, " << theArgc << ")."; throw OutOfRange(msg.str(), MODULE, __FILE__, __LINE__); @@ -76,7 +106,69 @@ //***************************************************************************** -// TestCase::header -//***************************************************************************** -std::ostream& TestCase::header() +// TestCase::execute() +//> Execute the test case ad generate formatted test report. This method +// performs the simple sequence: +// -# Output Header to the report stream +// -# Run steps for the test +// -# Output Footer to the report stream +// +// @return EXIT_SUCCESS on successful execution of all test steps. +// EXIT_FAILURE otherwise. +//< +//***************************************************************************** +Util_API +int +TestCase::execute() +{ + EXCEPTION_TRY("Damkjer::TestCase::execute()"); + + header(); + + theReportStream << BlockIndent(4); + // Indent the body of the test report by 4. + int results = steps(); + theReportStream << endBlock; + + footer(); + + return results; + + EXCEPTION_RETHROW; +} + +//***************************************************************************** +// TestCase::testing(const std::string&) +//> The formatted test leader. +// +// Return a string in the following format for consistent reports: +//- ". Testing ..." +// +// @param description The description to include in the test leader. +// @return The formatted testing string. +//< +//***************************************************************************** +void +TestCase::testing(const std::string& description) +{ + std::ostringstream oss; + oss << ++theStepCount << ". "; + + theDetailsIndent = static_cast(oss.str().length()); + + theReportStream << oss.str() << "Testing " << description << "...\n"; + + return; +} + +//***************************************************************************** +// TestCase::header() +//> Header for the unit test case report entry. This method is also +// responsible for starting the test case timer. +// +// @return The formatted test report header. +//< +//***************************************************************************** +std::ostream& +TestCase::header() { #if ( _WIN32 || _WIN64 ) @@ -98,5 +190,5 @@ // Indent this block by 4. - theReportStream << blockIndent(4); + theReportStream << BlockIndent(4); theReportStream << theCaseDescription << "\n"; theReportStream << endBlock; @@ -110,9 +202,52 @@ return theReportStream; } - + +//***************************************************************************** +// TestCase::steps() +//> Execute the registered steps for the test case. +// +// @return EXIT_SUCCESS on successful execution of all test steps. +// EXIT_FAILURE otherwise. +//< +//***************************************************************************** +int +TestCase::steps() +{ + EXCEPTION_TRY("Damkjer::TestCase::steps()"); + + bool testPassed = false; + unsigned int passedTests = 0; + + for (unsigned int i = 0; i < theSteps.size(); ++i) + { + testing(theSteps[i]->description()); + theReportStream << BlockIndent(theDetailsIndent); + testPassed = (*(theSteps[i]))(*this); + theReportStream << "\n" << ((testPassed) ? "[PASSED]" : "[FAILED]") + << "\n" << endBlock; + + if (testPassed) ++passedTests; + + theReportStream << sline; + } + + theReportStream << "Summary: " << passedTests << "/" << theSteps.size() + << " tests passed.\n"; + + return (passedTests == theSteps.size()) ? EXIT_SUCCESS : EXIT_FAILURE; + + EXCEPTION_RETHROW; +} + //***************************************************************************** // TestCase::footer -//***************************************************************************** -std::ostream& TestCase::footer() +//> Footer for the unit test case report entry. This method is also +// responsible for stopping the test case timer. +// +// @return The formatted test report footer. +//< +//***************************************************************************** +std::ostream& +TestCase::footer() { double elapsed = 0; @@ -135,5 +270,5 @@ #endif - unsigned int iElapsed = unsigned int(elapsed); + unsigned int iElapsed = static_cast(elapsed); std::stringstream msg; @@ -151,5 +286,4 @@ theReportStream -// << std::string(79,'-') << "\n" << sline << " STOP TIME : " << std::asctime(localtime(&now)) @@ -162,88 +296,3 @@ } -//***************************************************************************** -// TestCase::steps -//***************************************************************************** -int TestCase::steps() -{ - EXCEPTION_TRY("Damkjer::TestCase::steps()"); - - bool testPassed = false; - int passedTests = 0; - - for (int i = 0; i < theSteps.size(); ++i) - { - testing(theSteps[i]->description()); - theReportStream << blockIndent(theDetailsIndent); - testPassed = (*(theSteps[i]))(*this); - theReportStream << "\n" << ((testPassed) ? "[PASSED]" : "[FAILED]") - << "\n" << endBlock; - - if (testPassed) ++passedTests; - - theReportStream << sline; - } - - theReportStream << "Summary: " << passedTests << "/" << theSteps.size() - << " tests passed.\n"; - - return (passedTests == theSteps.size()) ? EXIT_SUCCESS : EXIT_FAILURE; - - EXCEPTION_RETHROW; -} - -//***************************************************************************** -// TestCase::execute -//***************************************************************************** -Util_API int TestCase::execute() -{ - EXCEPTION_TRY("Damkjer::TestCase::execute()"); - - header(); - - theReportStream << blockIndent(4); - // Indent the body of the test report by 4. - int results = steps(); - theReportStream << endBlock; - - footer(); - - return results; - - EXCEPTION_RETHROW; -} - -//***************************************************************************** -// TestCase::testing -//***************************************************************************** -void TestCase::testing(const std::string& description) -{ - std::ostringstream oss; - oss << ++theStepCount << ". "; - - theDetailsIndent = static_cast(oss.str().length()); - - theReportStream << oss.str() << "Testing " << description << "...\n"; - - return; -} - - -//***************************************************************************** -// TestCase::report -//***************************************************************************** -Util_API std::ostream& TestCase::report() -{ - return theReportStream; -} - -//***************************************************************************** -// TestCase::registerStep -//***************************************************************************** -Util_API std::size_t TestCase::registerStep(TestStep* step) -{ - theSteps.push_back(step); - return theSteps.size(); -} - -} +} Index: Damkjer/Util/UnitTest/TestCase.h =================================================================== --- Damkjer/Util/UnitTest/TestCase.h (revision 10) +++ Damkjer/Util/UnitTest/TestCase.h (revision 12) @@ -1,10 +1,14 @@ //***************************************************************************** -// FILE: UnitTest.h +// FILE: TestCase.h // // Copyright (C) 2013 Kristian Damkjer. // -// DESCRIPTION: -// -// LIMITATIONS: +// DESCRIPTION: +//> The interface definition for unit test cases. +//< +// +// LIMITATIONS: +//> No known limitations. +//< // // SOFTWARE HISTORY: @@ -14,27 +18,29 @@ //***************************************************************************** -#ifndef TestCase_HEADER -#define TestCase_HEADER +#ifndef Damkjer_TestCase_HEADER +#define Damkjer_TestCase_HEADER #if ( _WIN32 || _WIN64 ) - #if NOMINMAX -#include + #if NOMINMAX // Avoid macro definitions of min/max infavor of STL +#include // USES LARGE_INTEGER union #else - #define NOMINMAX -#include + #define NOMINMAX // Avoid macro definitions of min/max in favor of STL +#include // USES LARGE_INTEGER union #undef NOMINMAX #endif -#include #elif ( __linux || __unix || __posix ) -#include +#include // USES timespec structure +#else + // How else can we capture high-resolution timing information? #endif -#include -#include -#include -#include -#include - +#include // HASA std::ostream interface and data member. +#include // HASA std::string data member. +#include // HASA std::vector data member. + +// ISA component of the Util library API. #include "Util/UtilAPI.h" + +// HASA FormatFilter data member. #include "Util/Streams/FormatFilter.h" @@ -44,4 +50,6 @@ //***************************************************************************** // CLASS: TestCase +//> A common base class for unit test cases. +//< //***************************************************************************** class TestCase @@ -50,65 +58,76 @@ #if ( _WIN32 || _WIN64 ) typedef LARGE_INTEGER TimeT; + //> The time structure type for Windows systems. + //< #elif ( __linux || __unix || __posix ) typedef timespec TimeT; + //> The time structure type for *nix systems. + //< #else // How else can we capture high-resolution timing information? #endif - Util_API TestCase(int argc, char** argv, - const std::string& caseName, - const std::string& caseID, - const std::string& caseDescription, + class TestStep; + + Util_API TestCase(int argc, char**, + const std::string&, + const std::string&, + const std::string&, std::ostream& reportStream=std::clog); - //> This constructor sets the name, ID, and description for the unit test - // case. It also wraps an output stream with a report stream to easily - // redirect and format test logs. + //> Intialize a test case with required information. //< Util_API virtual ~TestCase(){} - //> Free resources owned by this class. + //> Destruct the TestCase and deallocate resources. //< Util_API virtual int execute(); - //> Execute the test case. This method performs the simple sequence: - // 1) Output Header to the report stream - // 2) Run steps for the test - // 3) Output Footer to the report stream + //> Execute the test case ad generate formatted test report. //< Util_API virtual std::ostream& report(); - //> - //< - - class TestStep - { - public: - Util_API TestStep(const std::string& description) - : theDescription(description) - { - } - - Util_API const std::string& description() const { return theDescription; } - - Util_API virtual bool operator()(TestCase&) const = 0; - - private: - std::string theDescription; - }; - - Util_API std::size_t registerStep(TestStep* step); + //> The test case report output stream. + //< + + Util_API std::size_t registerStep(TestStep* const); + //> Register a test step with the test case for execution. + //< Util_API int stepNum() const { return theStepCount; } + //> Identify the current step in test exection. + // + // @return The current step in execution. + //< Util_API int argc() const { return theArgc; } //> The command line argument count. - //< - - Util_API std::string argv(int i) const; + // + // @return The command line argument count. + //< + + Util_API std::string argv(int) const; //> The requested command line argument, converted to a string. //< + private: + TestCase(); + //> Explicitly disable the compiler-generated default constructor. No + // definition provided. + //< + + TestCase(const TestCase&); + //> Explicitly disable the compiler-generated copy constructor. No + // definition provided. + //< + + TestCase& operator=(const TestCase&); + //> Explicitly disable the compiler-generated assignment operator. No + // definition provided. + // + // @return The updated left-hand side when not disabled. + //< + void testing(const std::string&); - //> + //> The formatted test leader. //< @@ -118,5 +137,5 @@ int steps(); - //> + //> Execute the registered steps for the test case. //< @@ -125,50 +144,140 @@ //< + TimeT theStartTime; + //> The test case start time. + //< + + std::string theCaseName; + //> The test case name. + //< + + std::string theCaseID; + //> The test case identifier. + //< + + std::string theCaseDescription; + //> The test case description. + //< + + std::ostream& theReportStream; + //> The report output stream. + //< + + std::vector theSteps; + //> The test steps for evaluation. + //< + + FormatFilter theStreamFormatter; + //> The test report formatter. + //< + + char** theArgv; + //> The vector of arguments. + //< + + long theDetailsIndent; + //> The current report indentation level. + //< + int theArgc; - //> - //< - - char** theArgv; - //> - //< - - std::string theCaseName; - //> - //< - - std::string theCaseID; - //> - //< - - std::string theCaseDescription; - //> - //< - - std::ostream& theReportStream; - //> - //< - - long theDetailsIndent; - //> - //< - - TimeT theStartTime; - //> - //< - - std::vector theSteps; - //> + //> The argument count. //< int theStepCount; - //> - //< - - FormatFilter theStreamFormatter; - //> + //> The test step counter. //< }; +//***************************************************************************** +// CLASS: TestCase::TestStep +//> An individual step of a comprehensive test case. +//< +//***************************************************************************** +class TestCase::TestStep +{ +public: + Util_API explicit TestStep(const std::string& description) + : theDescription(description) + { + } + //> Instantiate a TestStep with a description. + // + // @param description The test step description. + //< + + Util_API virtual ~TestStep(){} + //> Destruct the TestStep and deallocate resources. + //< + + Util_API const std::string& description() const { return theDescription; } + //> The description of the test step. + // + // @return The test step description. + //< + + Util_API virtual bool operator()(TestCase&) const = 0; + //> Perform the evaluation of the test step. + // + // @return true if and only if the test step is successful. + //< + +private: + TestStep(); + //> Explicitly disable the compiler-generated default constructor. No + // definition provided. + //< + + TestStep(const TestStep&); + //> Explicitly disable the compiler-generated copy constructor. No + // definition provided. + //< + + TestStep& operator=(const TestStep&); + //> Explicitly disable the compiler-generated assignment operator. No + // definition provided. + // + // @return The updated left-hand side when not disabled. + //< + + std::string theDescription; + //> The description of the test step. + //< +}; + +//***************************************************************************** +// TestCase::report +//> The test case report output stream. +// +// @return the report stream for this test case. +//< +//***************************************************************************** +Util_API +inline +std::ostream& +TestCase::report() +{ + return theReportStream; } +//***************************************************************************** +// TestCase::registerStep +//> Register a test step with the test case for execution. +// +// @param step a pointer to a step to be executed as part of this test case. +// @return the test case step number associated with the registered +// step. +//< +//***************************************************************************** +Util_API +inline +std::size_t +TestCase::registerStep(TestStep* const step) +{ + theSteps.push_back(step); + return theSteps.size(); +} + + +} + #endif Index: Damkjer/Util/UnitTest/test/TestTestCase.cpp =================================================================== --- Damkjer/Util/UnitTest/test/TestTestCase.cpp (revision 9) +++ Damkjer/Util/UnitTest/test/TestTestCase.cpp (revision 12) @@ -38,5 +38,5 @@ #include -#include "damkjerConfig.h" +#include "Util/Exception/Exception.h" #include "TestTestCase.h" #include "Util/Streams/BlockIndent.h" @@ -172,6 +172,9 @@ static_cast(expStm.str().length()); - argStm << std::string(((pad < 0) ? -pad : 0), ' ') << ": "; - expStm << std::string(((pad > 0) ? pad : 0), ' ') << ": "; + unsigned int argPad = static_cast((pad < 0) ? -pad : 0); + unsigned int expPad = static_cast((pad > 0) ? pad : 0); + + argStm << std::string(argPad, ' ') << ": "; + expStm << std::string(expPad, ' ') << ": "; test.report() << argStm.str() << test.argv(i) << "\n" @@ -225,5 +228,5 @@ test.report() << "Caught expected exception:\n"; - test.report() << blockIndent() << e; + test.report() << BlockIndent() << e; e.stackTrace(test.report()); test.report() << endBlock; Index: Damkjer/Util/UnitTest/test/TestTestCase.h =================================================================== --- Damkjer/Util/UnitTest/test/TestTestCase.h (revision 9) +++ Damkjer/Util/UnitTest/test/TestTestCase.h (revision 12) @@ -29,4 +29,7 @@ //> //< +private: + TestTestCase(const TestTestCase&); + TestTestCase& operator=(const TestTestCase&); }; Index: Damkjer/Util/UnitTest/test/TestUnitTest.vcxproj =================================================================== --- Damkjer/Util/UnitTest/test/TestUnitTest.vcxproj (revision 10) +++ Damkjer/Util/UnitTest/test/TestUnitTest.vcxproj (revision 12) @@ -2,4 +2,12 @@ + + DebugOMP + Win32 + + + DebugOMP + x64 + Debug @@ -48,5 +56,13 @@ true + + Application + true + + Application + true + + Application true @@ -74,5 +90,11 @@ + + + + + + @@ -94,5 +116,13 @@ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ @@ -130,4 +160,25 @@ + + + + + + + _USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + Console + + setlocal @@ -171,4 +222,24 @@ + + + + + + + _USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) + true + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + Console + + setlocal @@ -247,4 +318,7 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) true + AnySuitable + true + Speed @@ -333,4 +407,8 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)\includes\eigen;%(AdditionalIncludeDirectories) true + /wd4514 /wd4571 /wd4668 /wd4710 /wd4711 /wd4820 /wd4986 %(AdditionalOptions) + AnySuitable + true + Speed Index: Damkjer/Util/UnitTest/test/test_TestCase.cpp =================================================================== --- Damkjer/Util/UnitTest/test/test_TestCase.cpp (revision 9) +++ Damkjer/Util/UnitTest/test/test_TestCase.cpp (revision 12) @@ -14,5 +14,5 @@ //***************************************************************************** -#include "damkjerConfig.h" +#include "Util/Exception/Exception.h" #include "TestTestCase.h" Index: Damkjer/Util/Util.vcxproj =================================================================== --- Damkjer/Util/Util.vcxproj (revision 10) +++ Damkjer/Util/Util.vcxproj (revision 12) @@ -2,4 +2,12 @@ + + DebugOMP + Win32 + + + DebugOMP + x64 + Debug @@ -28,5 +36,4 @@ - @@ -39,4 +46,11 @@ + + + + + + + @@ -60,5 +74,13 @@ true + + DynamicLibrary + true + + DynamicLibrary + true + + DynamicLibrary true @@ -86,5 +108,11 @@ + + + + + + @@ -103,8 +131,16 @@ + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)lib\$(Platform)\$(Configuration)\ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + $(SolutionDir)test-bin\$(Platform)\$(Configuration)\ + $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ + + $(SolutionDir)lib\$(Platform)\$(Configuration)\ $(SolutionDir)build\$(Platform)\$(Configuration)\$(ProjectName)\ @@ -133,4 +169,22 @@ Disabled $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) + + + MachineX86 + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win32\microsoft;%(AdditionalLibraryDirectories) + + + + + Util_DLL;_CRT_SECURE_NO_WARNINGS;_USE_MATH_DEFINES;WIN32;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) + true + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) @@ -148,4 +202,21 @@ Disabled $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) + + + true + libmx.lib;libmat.lib;libmex.lib;%(AdditionalDependencies) + $(SolutionDir)lib\$(Platform)\$(Configuration)\;$(MATLAB_R2012A)\extern\lib\win64\microsoft;%(AdditionalLibraryDirectories) + + + + + Util_DLL;_CRT_SECURE_NO_WARNINGS;_USE_MATH_DEFINES;WIN64;_DEBUG;_WINDOWS;TEMPLATE_INCLUSION;%(PreprocessorDefinitions) + MultiThreadedDebugDLL + Level4 + Disabled + $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) + true + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) @@ -161,4 +232,5 @@ Level4 $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) @@ -178,4 +250,5 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) true + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) @@ -194,4 +267,5 @@ Level4 $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) @@ -209,6 +283,10 @@ $(SolutionDir);$(MATLAB_R2012A)\extern\include;$(SolutionDir)includes\eigen;%(AdditionalIncludeDirectories) true - Level4 + EnableAllWarnings true + AnySuitable + true + Speed + 4514;4571;4668;4710;4711;4820;4986;%(DisableSpecificWarnings) Index: Damkjer/Util/Util.vcxproj.filters =================================================================== --- Damkjer/Util/Util.vcxproj.filters (revision 10) +++ Damkjer/Util/Util.vcxproj.filters (revision 12) @@ -19,15 +19,6 @@ Header Files - - Template Implementation Files - Header Files - - - Header Files - - - Template Implementation Files @@ -49,7 +40,4 @@ Header Files - - Header Files - Header Files @@ -63,4 +51,34 @@ Header Files + + + Template Implementation Files + + + Template Implementation Files + + + Template Implementation Files + + + Header Files + + + Header Files + + + Header Files + + + Header Files + + + Header Files + + + Header Files + + + Template Implementation Files Index: Damkjer/Util/UtilAPI.h =================================================================== --- Damkjer/Util/UtilAPI.h (revision 9) +++ Damkjer/Util/UtilAPI.h (revision 12) @@ -6,13 +6,15 @@ // // DESCRIPTION: -// Macro definitions for the Util Library API. +//> Macro definitions for the Util Library API. +//< // // LIMITATIONS: -// None. +//> No known limitations. +//< // // SOFTWARE HISTORY: -// 2013 JUL 26 K. Damkjer -// Initial Coding. -// +//> 2013-JUL-26 K. Damkjer +// Initial Coding. +//< //***************************************************************************** @@ -20,12 +22,26 @@ #define UtilAPI_HEADER +//***************************************************************************** +// MACRO: Util_API +//> Enable switching between exporting interfaces from a dynamic library and +// importing interfaces into a client application for the Util library API. +// This macro enables the explicit marking of modules that constitute the +// Util library API. We can then easily determine the correct action to take +// in the build process by defining a separate flag when building the +// library (Util_DLL). +//< +//***************************************************************************** #ifndef Util_API - #if _WINDLL + #if _MSC_VER + // Building a Windows DLL #if Util_DLL + // Building the library. #define Util_API __declspec(dllexport) #else + // Using the library. #define Util_API __declspec(dllimport) #endif #else + // Other shared libraries. #define Util_API #endif Index: Damkjer/Util/Widgets/timebar.m =================================================================== --- Damkjer/Util/Widgets/timebar.m (revision 9) +++ Damkjer/Util/Widgets/timebar.m (revision 12) @@ -1,6 +1,5 @@ % timebar Create a time-based waitbar. % -% File: -% timebar.m +% File: timebar.m % % Description: @@ -47,5 +46,25 @@ % Initial Coding. +%****************************************************************************** +% timebar +%****************************************************************************** function [handle] = timebar(step, steps, message, start, handle) + % Create a waitbar dialog with an estimated time to completion based on + % linear extrapolation from number of processing steps completed, number of + % processing steps remaining and current elapsed time. + % + % Parameters: + % step - Current processing step. + % + % steps - Total steps in process. + % + % message - Base message to be included in waitbar text. + % + % start - Process start time. + % + % handle - Figure handle for existing waitbar. + % + % Returns: + % handle - Figure handle for rendered timebar graphic. step = double(step); @@ -78,5 +97,18 @@ end +%****************************************************************************** +% timeString +%****************************************************************************** function [message] = timeString(seconds) + % Create a human-readable, order of magnitude appropriate interpretation of + % a time value. + % + % Parameters: + % seconds - Time as decimal seconds. + % + % Returns: + % message - Coarse order of magnitude interpretation of the seconds + % value. + if (seconds > 7200) message = [num2str(floor(seconds/3600)) 'h']; Index: Damkjer/applications/demo_curvcolor.m =================================================================== --- Damkjer/applications/demo_curvcolor.m (revision 0) +++ Damkjer/applications/demo_curvcolor.m (revision 12) @@ -1,9 +1,54 @@ -%% -% DEMO_NORMCOLOR +% demo_curvcolor Demonstrate point cloud curvature coloring. % -% Demonstrates the curvcolor function capability. +% File: demo_curvcolor.m % +% Description: +% Demonstrate point cloud curvature coloring. +% +% Limitations: +% No known limitations. +% +% Synopsis: +% [] = demo_curvcolor() +% +% Inputs: +% None. +% +% Outputs: +% None. +% +% Toolbox requirements: +% None. +% +% Script requirements: +% None. +% +% Data requirements: +% None. +% +% References: +% None. +% +% See Also: +% None. +% + +% Copyright (C) 2012 Kristian L. Damkjer. +% +% Software History: +% 2012-AUG-29 K. Damkjer +% Initial Coding. + +%****************************************************************************** +% demo_curvcolor +%****************************************************************************** function demo_curvcolor -dataFile='Serpent Mound Model LAS Data.las'; + % Demonstrate point cloud curvature coloring. The sample point cloud is + % hard-coded to be the Armstrong-Enderby Sample LAS file. This can be + % changed to any desired sample point cloud manually. + % + % TODO: Parameterize the sample point cloud input. + +dataFile='1815-3_Armstrong-Enderby_Sample1.las'; disp('Building MEX files...'); Index: Damkjer/applications/demo_normcolor.m =================================================================== --- Damkjer/applications/demo_normcolor.m (revision 0) +++ Damkjer/applications/demo_normcolor.m (revision 12) @@ -5,5 +5,5 @@ % function demo_normcolor -dataFile='Serpent Mound Model LAS Data.las'; +dataFile='1815-3_Armstrong-Enderby_Sample1.las'; disp('Building MEX files...'); Index: Damkjer/applications/demo_spatial_analyze.m =================================================================== --- Damkjer/applications/demo_spatial_analyze.m (revision 6) +++ Damkjer/applications/demo_spatial_analyze.m (revision 12) @@ -40,5 +40,5 @@ num2str(toc(resultsStart)) 's']); -sourceData.color=[uint16(double(intmax('uint16'))*results.dimensionality)]; +sourceData.color=(uint16(double(intmax('uint16'))*results.dimensionality)); outFile=[outPath '/dimcolor.las']; Index: mkjer/damkjerConfig.h =================================================================== --- Damkjer/damkjerConfig.h (revision 9) +++ (revision ) @@ -1,14 +1,0 @@ -#ifndef config_HEADER -#define config_HEADER - -#include "Util/Exception/Exception.h" - -#ifndef EXPORT - #if MAKE_DEPENDING || TEMPLATE_INCLUSION - #define EXPORT - #else - #define EXPORT export - #endif -#endif - -#endif