Package: captif-slp
captif-slpThecaptif-slpPython package can be used to calculate the Mean Profile Depth (MPD) of a road surface according toISO 13473-1:2019Characterization of pavement texture by use of surface profiles — Part 1: Determination of mean profile depth.The software has been developed at the Waka Kotahi NZ Transport AgencyCAPTIF Road Research Centrefor use with the CAPTIF in-house Stationary Laser Profilometer (SLP). While some methods are specific to data captured using the CAPTIF SLP instrument the software can also be used to calculate MPD of other road surface profiles provided the data is converted to a valid format before processing.Refer to theEuropean Road Profile Users' Groupwebsite for further information on ISO 13473-1 including a MATLAB implementation and a set of reference profiles and results.Also refer toTransfund New Zealand Research Report 84for details of the original Stationary Laser Profilometer developed in 1997 for use by Transit New Zealand. This instrument was based on the VTI stationary laser profilometer.Installationcaptif-slpcan be installed by runningpip install captif-slp.The package requires Python 3.9 to run.UsageThe Reading objectTheReadingclass provides a mechanism to interact with an individual road surface profile and can be imported usingfrom captif_slp import Reading.A newReadingobject must be created using one of the following class methods.From a DataFrame containingdistance_mmandrelative_height_mmcolumns:reading=Reading.from_trace(trace:DataFrame,meta:Optional[dict]=None,...)Themetakeyword argument provides a mechanism for attaching meta data to aReadingobject. This can be used to include information such as a file name, reading number or measurement date. The data can be accessed later from themetaattribute.Or from a validtexturedata file capable of being read using thecaptif-data-structurespackage (i.e. a CAPTIF in-house file format):reading=Reading.from_file(path:Union[str,Path],parallel:bool=True,...)Theparallelkeyword argument allows the file to be read using the Pythonmultiprocessingmodule. This can significantly speed up load times for large files. Note that where several files are being processed it is more efficient to pass individual files to each CPU core for processing in which caseparallelmust be set to Falseto allow the multiprocessing module to be used by a higher level function.The remaining keyword arguments are common forReading.from_trace()andReading.from_file():reading=Reading.from_...(...segment_length_mm:int=100,target_sample_spacing_mm:float=0.5,evaluation_length_m:Optional[float]=None,alpha:int=3,start_mm:Optional[float]=None,end_mm:Optional[float]=None,detect_plates:bool=False,)The keyword arguments have the following meanings:segment_lenght_mm--default: 100Length of the segments (in millimetres) that the profile is split into for processing. Note that this should generally be left as the default value of 100 mm as this is the required segment length in ISO 13473-1.target_sample_spacing_mm--default: 0.5The sample spacing (in millimetres) used by the resampling process. ISO 13473-1:2019 calls for a road surface profile to be resampled to either 0.5 mm or 1.0 mm depending on the sample spacing in the original profile. In general 0.5 mm should be used where the original sample spacing is less than or equal to 0.5 mm.evaluation_length_m--default: NoneThe evaluation length (in metres) over which the mean profile depth is reported. The default behaviour is to calculate MPD for the entire road surface profile. For spot measurements taken using a Stationary Laser Profilometer (SLP) the default behaviour is appropriate. For continuous measurements it is usually more useful to report MPD over shorter sections in which case the evaluation length could be set to 10 or 20 metres.alpha--default: 3The constant used in the spike detection criterion (Eqn E.1, ISO 13473-1:2019). The default value of 3 is the value suggested in the standard. Note that a value of 3 used with profiles taken using the CAPTIF SLP results in a large number of false positives when analysing highly texture surfaces in New Zealand (e.g. chipseals). A value of 6 has been found to yield good results on profiles taken using the CAPTIF SLP instrument.start_mm--default: NoneUsed to remove a section from the beginning of the profile before processing. The default is use the full profile. The value is ignored if thedetect_platesis set to True.end_mm--default: NoneUsed to remove a section from the end of the profile before processing. The default is use the full profile. The value is ignored if thedetect_platesis set to True.detect_plates--default: FalseUsed to detect reference plates at the start and/or end of the profile and trim the profile accordingly. For historical reasons reference plates are present on the CAPTIF SLP instrument to signal the start and end of the section of interest; these reference plates (along with the sections of profile outside of them) need to be removed from the profile before processing. The default behaviour is to not preform this step as it is unique to the CAPTIF SLP instrument.Accessing the resultsOnce a profile has been successfully loaded into aReadingobject the following instance methods can be used to access the results.reading.msd()-- Mean Segment Depth (MSD)Returns a list of dictionaries containing MSD values for each segment (usually 100 mm long) in the profile. Eachdictelement in the list has the following keys:segment_no: int- segment position number (int).msd: float- mean segment depth.valid: bool- segment validity (i.e. meets the maximum dropouts and spikes requirement).evaluation_length_position_m: Optional[float]- evaluation length position.reading.mpd(include_meta: bool = False)-- Mean Profile Depth (MPD)Returns either a single dictionary if evaluation length is not set, or a list of dictionaries if evaluation length is set. Thedictelement(s) have the following keys:distance_m- evaluation length position (Noneif evaluation length is not set).mpd- mean profile depth (average MSD across all valid segments).stdev- standard deviation (standard deviation of MSD from all valid segments).valid_segments- number of valid segments in the profile.proportion_valid_segments- proportion of valid segments in the profile.is_valid- result validity (i.e. whether or not valid_segment_ration >= 0.5).(meta data fields) - the meta data fields ifinclude_metais set to True.Bulk processingIn order to provide efficient processing the Pythonmultiprocessingmodule is used to process batches of valid data files meeting the CAPTIF in-housetexturefile format. The processing function can be imported usingfrom captif_slp import process_files.The function takes the path of a folder containing the files to be processed and returns a list of results as perReading.mpd(include_meta=True)with the addition of afilenameandfolderfield.results=process_files(path:Union[str,Path])process_filesuses the following settings under the hood as these are the settings relevant to profiles taken using the CAPTIF SLP instrument:segment_lenght_mm = 100target_sample_spacing_mm = 0.5evaluation_length_m = Nonealpha = 6detect_plates = TrueTo access all attributes fromReading.from_file(except theparallelattribute which is set to False internally to allow themultiprocessingmodule to be used by a higher level) usecaptif_slp.process.process_generic_files.IssuesPlease submit an issue if you find a bug or have an idea for an improvement.LicenseThe software is provided under the following license.MIT LicenseCopyright (c) 2021 CAPTIF Road Research CentrePermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.