Merge pull request #76432 from paulth1/cognitive-services-face-articles-batch1

edit pass: Cognitive services face articles batch1

Author: ShawnJackson

articles/cognitive-services/Face/Face-API-How-to-Topics/HowtoDetectFacesinImage.md

@@ -15,29 +15,29 @@ ms.author: sbowles
 
 # Get face detection data
 
-This guide will demonstrate how to use face detection to extract attributes like gender, age, or pose from a given image. The code snippets in this guide are written in C# using the Face API client library, but the same functionality is available through the [REST API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+This guide demonstrates how to use face detection to extract attributes like gender, age, or pose from a given image. The code snippets in this guide are written in C# by using the Azure Cognitive Services Face API client library. The same functionality is available through the [REST API](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
 
-This guide will show you how to:
+This guide shows you how to:
 
 - Get the locations and dimensions of faces in an image.
-- Get the locations of various face landmarks (pupils, nose, mouth, and so on) in an image.
-- Guess the gender, age, and emotion, and other attributes of a detected face.
+- Get the locations of various face landmarks, such as pupils, nose, and mouth, in an image.
+- Guess the gender, age, emotion, and other attributes of a detected face.
 
 ## Setup
 
-This guide assumes you have already constructed a **[FaceClient](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceclient?view=azure-dotnet)** object, named `faceClient`, with a Face subscription key and endpoint URL. From here, you can use the face detection feature by calling either **[DetectWithUrlAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithurlasync?view=azure-dotnet)** (used in this guide) or **[DetectWithStreamAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithstreamasync?view=azure-dotnet)**. See the [Detect Faces quickstart for C#](../quickstarts/csharp-detect-sdk.md) for instructions on how to set this up.
+This guide assumes that you already constructed a [FaceClient](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceclient?view=azure-dotnet) object, named `faceClient`, with a Face subscription key and endpoint URL. From here, you can use the face detection feature by calling either [DetectWithUrlAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithurlasync?view=azure-dotnet), which is used in this guide, or [DetectWithStreamAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.faceoperationsextensions.detectwithstreamasync?view=azure-dotnet). For instructions on how to set up this feature, see the [Detect faces quickstart for C#](../quickstarts/csharp-detect-sdk.md).
 
-This guide will focus on the specifics of the Detect call—what arguments you can pass and what you can do with the returned data. We recommend only querying for the features you need, as each operation takes additional time to complete.
+This guide focuses on the specifics of the Detect call, such as what arguments you can pass and what you can do with the returned data. We recommend that you query for only the features you need. Each operation takes additional time to complete.
 
 ## Get basic face data
 
-To find faces and get their locations in an image, call the method with the _returnFaceId_ parameter set to **true** (default).
+To find faces and get their locations in an image, call the method with the _returnFaceId_ parameter set to **true**. This setting is the default.
 
 ```csharp
 IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(imageUrl, true, false, null);
 ```
 
-The returned **[DetectedFace](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.detectedface?view=azure-dotnet)** objects can be queried for their unique IDs and a rectangle which gives the pixel coordinates of the face.
+You can query the returned [DetectedFace](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.detectedface?view=azure-dotnet) objects for their unique IDs and a rectangle that gives the pixel coordinates of the face.
 
 ```csharp
 foreach (var face in faces)
@@ -47,17 +47,17 @@ foreach (var face in faces)
 }
 ```
 
-See **[FaceRectangle](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.facerectangle?view=azure-dotnet)** for information on how to parse the location and dimensions of the face. Usually, this rectangle contains the eyes, eyebrows, nose, and mouth; the top of head, ears, and chin are not necessarily included. If you intend to use the face rectangle to crop a complete head or mid-shot portrait (a photo ID type image), you may want to expand the rectangle by a certain margin in each direction.
+For information on how to parse the location and dimensions of the face, see [FaceRectangle](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.facerectangle?view=azure-dotnet). Usually, this rectangle contains the eyes, eyebrows, nose, and mouth. The top of head, ears, and chin aren't necessarily included. To use the face rectangle to crop a complete head or get a mid-shot portrait, perhaps for a photo ID-type image, you can expand the rectangle in each direction.
 
 ## Get face landmarks
 
-[Face landmarks](../concepts/face-detection.md#face-landmarks) are a set of easy-to-find points on a face such as the pupils or the tip of nose. You can get face landmark data by setting the _returnFaceLandmarks_ parameter to **true**.
+[Face landmarks](../concepts/face-detection.md#face-landmarks) are a set of easy-to-find points on a face, such as the pupils or the tip of the nose. To get face landmark data, set the _returnFaceLandmarks_ parameter to **true**.
 
 ```csharp
 IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(imageUrl, true, true, null);
 ```
 
-The following code demonstrates how you might go on to retrieve the locations of the nose and pupils:
+The following code demonstrates how you might retrieve the locations of the nose and pupils:
 
 ```csharp
 foreach (var face in faces)
@@ -75,7 +75,7 @@ foreach (var face in faces)
 }
 ```
 
-Face landmarks data can also be used to accurately calculate the direction of the face. For example, we can define the rotation of the face as a vector from the center of the mouth to the center of the eyes. The code below calculates this vector:
+You also can use face landmarks data to accurately calculate the direction of the face. For example, you can define the rotation of the face as a vector from the center of the mouth to the center of the eyes. The following code calculates this vector:
 
 ```csharp
 var upperLipBottom = landmarks.UpperLipBottom;
@@ -97,13 +97,13 @@ Vector faceDirection = new Vector(
     centerOfTwoEyes.Y - centerOfMouth.Y);
 ```
 
-Knowing the direction of the face, you can then rotate the rectangular face frame to align it more properly. If you want to crop faces in an image, you can programmatically rotate the image so that the faces always appear upright.
+When you know the direction of the face, you can rotate the rectangular face frame to align it more properly. To crop faces in an image, you can programmatically rotate the image so that the faces always appear upright.
 
 ## Get face attributes
 
-Besides face rectangles and landmarks, the face detection API can analyze several conceptual attributes of a face. See the [Face attributes](../concepts/face-detection.md#attributes) conceptual section for a full list.
+Besides face rectangles and landmarks, the face detection API can analyze several conceptual attributes of a face. For a full list, see the [Face attributes](../concepts/face-detection.md#attributes) conceptual section.
 
-To analyze face attributes, set the _returnFaceAttributes_ parameter to a list of **[FaceAttributeType Enum](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.faceattributetype?view=azure-dotnet)** values.
+To analyze face attributes, set the _returnFaceAttributes_ parameter to a list of [FaceAttributeType Enum](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.vision.face.models.faceattributetype?view=azure-dotnet) values.
 
 ```csharp
 var requiredFaceAttributes = new FaceAttributeType[] {
@@ -118,7 +118,7 @@ var requiredFaceAttributes = new FaceAttributeType[] {
 var faces = await faceClient.DetectWithUrlAsync(imageUrl, true, false, requiredFaceAttributes);
 ```
 
-Then, get references to the returned data and do further operations according to your needs.
+Then, get references to the returned data and do more operations according to your needs.
 
 ```csharp
 foreach (var face in faces)
@@ -134,11 +134,11 @@ foreach (var face in faces)
 }
 ```
 
-To learn more about each of the attributes, refer to the [Face detection and attributes](../concepts/face-detection.md) conceptual guide.
+To learn more about each of the attributes, see the [Face detection and attributes](../concepts/face-detection.md) conceptual guide.
 
 ## Next steps
 
-In this guide you learned how to use the various functionalities of face detection. Next, integrate these features into your app by following an in-depth tutorial.
+In this guide, you learned how to use the various functionalities of face detection. Next, integrate these features into your app by following an in-depth tutorial.
 
 - [Tutorial: Create a WPF app to display face data in an image](../Tutorials/FaceAPIinCSharpTutorial.md)
 - [Tutorial: Create an Android app to detect and frame faces in an image](../Tutorials/FaceAPIinJavaForAndroidTutorial.md)