ExportReport (arcpy.mapping)
Récapitulatif
Exporte un rapport formaté, tabulaire à l'aide de données de couches ou de tables autonomes dans un document ArcMap avec les informations du modèle de rapport fournies dans un fichier de mise en page du rapport (.rlf).
Discussion
La fonction ExportReport fournit un mécanisme pour automatiser la génération des rapports initialement créés dans un document ArcMap (.mxd) en utilisant les outils de génération de rapports proposés dans ArcMap. Le fichier de mise en page du rapport créé dans ArcMap est un modèle dans lequel sont stockées les informations sur le contenu et l'emplacement des éléments dans un rapport. Le fichier de mise en page du rapport permet ,avec les données source contenues dans un document ArcMap, de créer des rapports en sortie. Les données source peuvent également avoir des jointures associées et des informations de table connexes utilisées au sein du rapport.
Remarque :La fonction ExportReport a une dépendance sur l'installation ArcMap. Par conséquent vous ne pouvez exécuter la fonction ExportReport que sur des machines hébergeant ArcMap. ExportReport ne s'exécute pas avec des installations autonomes d'ArcGIS Engine ou ArcGIS for Server. En outre, la fonction ExportReport ne fonctionne pas comme une service de géotraitement.
Les données source doivent exister dans un document ArcMap (.mxd) ou un fichier de couches (.lyr), et les noms de champ du jeu de données doivent correspondre à ceux contenus dans le fichier de mise en page du rapport pour que la fonction ExportReport s'exécute correctement. Vous pouvez utiliser le fichier de mise en page du rapport avec différentes sources de données dans la mesure où le nom de la source de données correspond au nom du champ du jeu de données. Si les données sont similaires, mais que les noms de champ sont différents, alors vous pouvez utiliser le paramètre field_map pour remapper les champs du fichier de mise en page du rapport aux différents noms de champ du jeu de données source.
Il existe de nombreux éléments créés dans un fichier de mise en page du rapport dans ArcMap qui ne sont pas directement exposés via la fonction ExportReport. Il peut être judicieux de créer un jeu de modèles spécifiques pour générer et exporter les différents scénarios de rapport.
Les outils de génération de rapports de l'interface utilisateur d'ArcMap sont associés à un bouton appelé Options du jeu de données. Ce bouton permet à l'auteur de choisir comment traiter les enregistrements parmi les quatre manières proposées : Tout, Jeu sélectionné, Etendue visible et Requête de définition. Le paramètre dataset_option remplit ce même objectif et utilise un mot-clé. Avec une définition du paramètre dataset_option sur TOUT ou SELECTIONNE, seuls les enregistrements appropriés sont traités. Si le paramètre dataset_option est défini sur DEFINITION_QUERY, vous devez indiquer une chaîne valide pour le paramètre report_definition_query. Si le paramètre dataset_option est défini sur ETENDUE, vous devez fournir un objet Etendue valide pour le paramètre Etendue.
Comme pour l'interface utilisateur, vous ne pouvez utiliser qu'un seul mot-clé dataset_option à la fois. Par exemple, dans l'interface utilisateur, il n'est pas possible de traiter uniquement l'ensemble sélectionné d'enregistrements et uniquement ceux de l'étendue visible. La même règle s'applique à la fonction ExportReport ; vous ne pouvez définir qu'un seul paramètre à la fois. Si vous définissez plusieurs de ces paramètres, le dernier défini écrase le précédent et ainsi de suite. Vous pouvez toutefois combiner l'attribut ArcPy standard et/ou les fonctions de requête spatiale et les associer à la valeur SELECTIONNE du paramètre dataset_option pour générer le rapport final souhaité. Vous trouverez un exemple ci-après.
Le paramètre page_range permet de générer un rapport pour un sous-ensemble de pages uniquement. Il peut s'agir d'un groupe de pages continues (5-12), voire d'un ensemble discontinu de pages (3,7). Dans ce cas, lorsque vous générez un rapport et que le paramètre starting_page_number est défini sur 1, les numéros de page imprimés correspondent à ce que vous avez saisi (Page 3, Page 7). Cette fonction a été développée afin de pouvoir réimprimer un nombre sélectionné de pages pour les insérer dans des rapports existants. Si la demande implique que les numéros de page générées soient continus, par exemple (Page 1, Page 2), la valeur du paramètre starting_page_number doit être égale au numéro de page recherché et le paramètre page_range doit correspondre à une page unique. Vous devrez donc exécuter la fonction ExportReport pour chaque page. Par exemple, une fois avec le paramétrage starting_page_number = 3, page_range="3" et une nouvelle fois avec le paramétrage starting_page_number = 7, page_range="7".
Le paramètre field_map est utile uniquement si les noms de champ du jeu de données sont différents de ceux du paramètre source_data et des noms de champ utilisés pour créer le fichier de mise en forme du rapport. A la création du paramètre field_map, seuls les champs utilisés dans le rapport doivent être ajoutés au dictionnaire. Si les champs sont supprimés du dictionnaire de mappage des champs, ces champs sont supprimés du rapport. Les champs mappés doivent avoir des types de données identiques, et les noms de champ du paramètre field_map doivent respecter la case.
Il est possible d'utiliser arcpy.mapping pour créer des rapports afin que vous puissiez y inclure une carte. Les images contenues dans un rapport sont associées à une propriété appelée Image source. Arcpy.mapping ne peut pas accéder à cette valeur. En revanche, si la valeur de l'image source pointe vers un chemin sur le disque, arcpy.mapping peut mettre à jour le fichier sur le disque via une opération d'export ; le moteur de génération des rapports peut alors utiliser l'image disponible. Dans un exemple de pages dynamiques, vous pourriez modifier l'image en fonction de l'étendue actuelle, par exemple avec arcpy.mapping avant d'appeler la page suivante. Vous trouverez un exemple ci-après.
Pour plus d'informations sur la génération de rapports dans ArcGIS, consultez les rubriques d'introduction suivantes :
Syntaxe
| Paramètre | Explication | Type de données |
report_source | Object | |
report_layout_file |
A string that represents the path and file name of the report layout file (.rlf). | String |
output_file |
A string that represents the path and file name of the output file. The specified file extension controls the output format. The following extensions/formats are supported: .htm, .html, .pdf, .rtf, .tif, .tiff, .txt, and .xls. | String |
dataset_option |
A keyword that specifies which dataset rows will be processed in the output report. This value will override the Dataset Options value stored in the report layout file which is found in the Report Properties dialog box. If the dataset_option parameter is not set, it will default to the value stored in the report layout file. If the dataset_option is set to DEFINITION_QUERY, then a valid string needs to be provided for the report_definition_query parameter. If the dataset_option is set to EXTENT, then a valid Extent object needs to be provided for the extent parameter. Because the dataset_option keyword controls which additional parameter to use, only one of these parameters can be set at a time, just like in the user interface.
(La valeur par défaut est USE_RLF) | String |
report_title |
A string that represents the report's title which appears in the report layout file header section. | String |
starting_page_number |
A number that represents the printed page number for the first page of the output report. This value is useful for offsetting page numbers for reports that get appended to the end of existing documents. (La valeur par défaut est 1) | Long |
page_range |
A string that identifies the report pages to be exported to file (for example, 1, 3, 5–12). | String |
report_definition_query |
A string that represents a valid definition query that controls which rows will be exported to the output report. This parameter can only be set if the dataset_option parameter is set to DEFINITION_QUERY.This value will overwrite any settings stored in the report layout file. If the report_source layer or table has an existing definition query, then the report_definition_query will be applied to the existing subset of records. | String |
extent |
A geoprocessing Extent object. This parameter can only be set if the dataset_option parameter is set to EXTENT. When an extent object is passed into this parameter, the rows will be based on those features that intersect the extent. | Extent |
field_map |
This parameter allows you to use a report layout file with a data source that has similar data types but different field names. A dictionary of mapped field names is used to remap the fields used in the report layout file with the new fields in the data source. The following shows an example of the field_map dictionary structure: | Dictionary |
Exemple de code
Le script suivant va permettre d'exporter un rapport vers un fichier PDF à l'aide des entités sélectionnées de la couche dans le document ArcMap. Etant donné que d'autres paramètres facultatifs sont ignorés, le nom du paramètre de l'étendue est saisi explicitement.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Accidents", df)[0]
arcpy.mapping.ExportReport(lyr,
r"C:\Project\Project.rlf",
r"C:\Project\Output\ProjectReport.pdf",
"EXTENT",
extent=df.extent)
del mxd
Le script suivant étend l'exemple précédent pour montrer comment combiner une sélection spatiale et une sélection attributaire pour générer le rapport souhaité. Ceci est obligatoire car vous ne pouvez utiliser qu'un seul paramètre dataset_option à la fois. Les résultats sont combinés en une seule sélection qui utilise la valeur SELECTIONNE pour le paramètre dataset_option.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Accidents", df)[0]
#The DataFrame extent object is converted into a polygon feature so it can be used with the SelectLayerByLocation function.
dfAsFeature = arcpy.Polygon(arcpy.Array([df.extent.lowerLeft, df.extent.lowerRight, df.extent.upperRight, df.extent.upperLeft]),
df.spatialReference)
arcpy.SelectLayerByLocation_management(lyr, "INTERSECT", dfAsFeature, "", "NEW_SELECTION")
arcpy.SelectLayerByAttribute_management(lyr, "SUBSET_SELECTION", "\"Accidents\" > 3")
arcpy.mapping.ExportReport(lyr,
r"C:\Project\Project.rlf",
r"C:\Project\Output\ProjectReport.pdf",
"SELECTED")
del mxd
Le script suivant utilise le fichier de mise en page d'un rapport existant avec un jeu de données différent et des noms de champ différents. Un nouveau titre permet de remplacer le titre du fichier de mise en page du rapport et les champs sont de nouveau mappés à l'aide du paramètre field_map.
import arcpy
mxd = arcpy.mapping.MapDocument(r"C:\Project\Project.mxd")
df = arcpy.mapping.ListDataFrames(mxd, "Transportation")[0]
lyr = arcpy.mapping.ListLayers(mxd, "Traffic Lights", df)[0]
arcpy.mapping.ExportReport(lyr,
r"C:\Project\Project.rlf",
r"C:\Project\Output\ProjectReport.pdf",
report_title="Traffic Light Coordinates",
field_map={'Accidents':'LightID','X':'Longitude','Y':'Latitude'})
del mxd
Le script suivant montre comment insérer une carte dans un rapport. Un rapport de plusieurs pages sera généré. Chaque page contient une grande image qui affiche l'étendue actuelle du bloc de données, ainsi qu'un rapport qui fournit des informations sur les entités de l'étendue. Lorsque l'étendue du bloc de données est modifiée, le bloc de données est exporté vers un fichier .emf et la fonction ExportReport permet de créer un fichier PDF unique. Toutes les pages sont combinées en un seul document final au format PDF.
import arcpy, os
path = os.getcwd() #a relative path allowing for easy packaging
#Create PDF and remove if it already exists
pdfPath = path + r"\States_SubRegions.pdf"
if os.path.exists(pdfPath):
os.remove(pdfPath)
pdfDoc = arcpy.mapping.PDFDocumentCreate(pdfPath)
subRegionList = ["East North Central", "East South Central", "Middle Atlantic",
"Mountain", "New England", "Pacific", "South Atlantic",
"West North Central", "West South Central"]
mxd = arcpy.mapping.MapDocument(path + r"\States_SubRegions.mxd")
df = arcpy.mapping.ListDataFrames(mxd)[0]
lyr = arcpy.mapping.ListLayers(mxd, "States")[0]
pageCount = 1
for region in subRegionList:
#Generate image for each sub region
whereClause = "\"SUB_REGION\" = '" + region + "'"
lyr.definitionQuery = whereClause
arcpy.SelectLayerByAttribute_management(lyr, "NEW_SELECTION", whereClause)
df.extent = lyr.getSelectedExtent()
arcpy.SelectLayerByAttribute_management(lyr, "CLEAR_SELECTION")
arcpy.mapping.ExportToEMF(mxd, path + "\RegionalPicture.emf", df) #single file
#Generate report
arcpy.mapping.ExportReport(report_source=lyr,
report_layout_file=path + r"\States_SubRegions.rlf",
output_file=path + r"\temp" + str(pageCount) + ".pdf",
starting_page_number=pageCount)
#Append pages into final output
pdfDoc.appendPages(path + r"\temp" + str(pageCount) + ".pdf")
os.remove(path + r"\temp.pdf")
pageCount = pageCount + 1
pdfDoc.saveAndClose()
del mxd